A program to help you manage your projects and your chaotic home directory.

- It doesn't work!

- Yes, it does. Hopefully. :-)

First thing you, really, have to do is to change the value of the variable "doneconfiguring" to "Yes" (note capitalisation). Otherwise the existing mechanism to prevent you from using the script without actually ever looking into it kicks in and prevents you from doing just that. Then it should work.

You shouldn't be afraid to change the code to fit your needs. Take your medicine. Eat your vegetables. Learn the shell. Try harder.

This script is called "prj", but it can be called anything you want, really. Just change the name of the file. If you do that, then remember to rename the ".prj" configuration subdirectory accordingly in every project as well. More on that in a short while.

We will use the "prj" default name throughout our present documentation effort.

The whole idea is that you keep your work organised into projects. Each project in its own directory, placed, itself, in one of some special directories corresponding to categories you create yourself.

If you dare to look inside the script (and you really should, as we discussed before), you'll notice there is a place to name the directory that will be hosting your current projects (the working category, or, as usualy is named, the "Desktop"). Another directory will host all other categories, containing, themselves, other projects. Each project is, itself, a directory with some standard content inside to make the project manageable by the script.

Here's the required ASCIIart example:

 ~\
[-] Desktop
 |  [-] Current_project_1\
 |   |  [+] .git\
 |   |  [+] .prj\
 |   |   |  README
 |   |   |  TODO
 |   |   \  trash\
 |  [+] Current_project_2\
[-] Projects\
 |  [-] 1.Category_1\
 |   |  [+] a_delayed_project\
 |   |  [+] another_delayed_project\
 |   \  [+] third_one\
 |  [-] 2.Category_2\
 |   |  [+] An_extra_delayed_project\
 |   \  [+] Never_gonna_get_to_touch_this\
...

You'll notice the "Projects" directory is not a subdirectory of the "Desktop". That is so that it doesn't count as a project itself. The directory containing your categories (which contain themselves the projects) should not be one. You can arrange it to be hidden or somehow outside of your working directory.

Categories are the directories directly inside the projects directory (there is only one level of categories). They are named and prefixed after their directory names. Anything before a first dot in the name of the directory is the prefix. Anything after that is the category name. The prefix is used to sort them and as a short name for the category. So, if you want your "VeryUrgent" category to come before "QuiteUrgent" category, and that before "NotUrgent", name the directories a.VeryUrgent, b.QuiteUrgent and c.NotUrgent, for example.

You can refer to the category by its name or by its prefix. Which is handy, since it's short.

The prefix will not, normally, be shown unless you dig manually inside the projects directory.

Each category can, then, hold as many projects as you like. Use them to categorise your projects by whatever criteria you might come up with. Just choose wisely or you'll be very sorry very soon.

You can move projects from one category to another as you see fit.

Projects are the "atoms" of the whole thing.

Each project is a directory stored inside one of the categories. Let's take a look at what should be inside that directory.

1. A ".git" subdirectory. You can delete it if you don't want the project under git. Because of git, you might also have a ".gitignore" file. You can use this file to tell git to ignore the trash directory, if you wish (see below).

2. The ".prj" subdirectory. This is a configuration directory. You can use it to store a few items that, not being meant to be seen, are important for the behaviour of the script in relation to the particular project it is placed under. Keep it, you need it.

The name of this directory is ".prj" because the default name of the script is "prj". If ever you choose to rename the script something else, you have to change the name of this directory accordingly in every ancient project. Just look for how to use the for loop in your shell's manual. New projects will have it correctly named.

Inside this directory you can place scripts, meant to be run both: by the script using the mechanism prepared for that, and manually. For that to work, and for a nice integration with the script, the scripts must be executable files (obviously) named whatever you like but with a ".sh" extension. They must, also, print to stdout a line with a little self description if called with "aboutme" as first and only argument, and a help message, if that argument is "help".

You can also place special files indicating the relationship the project has with other projects. The script recognises "depends" as a dependency so far, and refuses to archive a project that still has dependencies. The content of these files is not used by the script at the moment, so you can use it to store notes about the reason why a project might be dependent on another.

You can also make use of this directory for other means you make up yourself (the idea of logs comes to mind, or new relations).

It is a good idea to keep this directory under git control.

3. A README file (note capitalisation) just like this one, documenting your project. The first line of this file will be used as the description of your project.

4. A TODO file. Used to keep track of tasks related to the project.

The "TODO" file (note capitalisation) is where you keep track of tasks related to the project. Each line beginning with a "*" followed by a space and one of "TODO" or "DONE" (note capitalisation again) is a task to be dealt with or already done, respectively.

The resemblance with an org-mode file is not a coincidence. It is meant to be a super simplified one, so you can take advantage of the amazing work folks from the org-mode team did for us. If you never heard of it, look it up on the Internet.

5. A "trash" subdirectory. It's meant to store, well... trash: temporary files, notes, references to external objects... everything not truly belonging to the product of the project it is placed under, but somehow related. You can delete it after you are done with the project (all tasks have been completed), before you archive the project, to save space, or never have it in the first place (delete it since the beginning) if that's a really simple project or if it doesn't make sense. It is not required. This is a good candidate to populate your ".gitignore" file.

- OK. So let's make use of it, then.

The script accepts what we call "verbs" (they might not be actual verbs, in the grammatical sense) as its first argument. If you don't provide a valid one, it will fail printing a standard help message to stdout and fail.

If you do provide one of the following, the script will execute as follows:

"done" - The project entered as next argument will be packed with a timestamp prefixed to its name and moved to the archives directory.

"find" - Will search for a string of text in every REDME and TODO file. Haven't I told you the for loop of your shell is awesome?

"fix" - Will turn a standard directory into a valid project or try to fix an invalid one (creating the README and TODO files, the trash and .prj subdirectories and initialising the VCS system).

"help" - The standard help message will be printed as when you do any mistake, but the script will not fail.

"kill" - Will kill a project in the working directory by recursively deleting it's directory. You will be prompted because there is no easy way back.

"killcategory" - Will kill an empty category by deleting its directory.

"list" or simply "ls" - If category names are provided as arguments only projects in said categories will be listed. If none is specified, all categories are listed preceded by an empty line and the category name inside square brackets.

"listarchives" or "lsa" - Will list the projects you archived.

"listcategories" or "lsc", for short - Will print the categories names. Simple.

"listprojects" or only "lsp" - Will print all projects sorted alphabetically and in reverse order of the categories (the one with the precedent prefix is the last one to be printed).

"move" or "mv" - Will move a project from one category to another.

"new" - Will create a new project in your first category with all it needs: the "README" and "TODO" files, the ".prj" and "trash" subdirectories and, if you have a VCS system, the project will be initialised in that VCS.

"newcategory" - Creates a new category. This one was easy.

"read" - Will open the "README" file in your preferred text editor.

"redo" - Will unarchive the last version of an archived project and place it in your first category. The archive will not be removed.

"rename" or "rn" - Renames a project. Easy too.

"renamecategory" or "rnc" - Will rename a category (include a prefix in the new name).

"run" - Runs a script belonging to a given project, stored in its ".prj" directory. You don't include the ".sh" suffix in the name of the script when calling it using this mechanism. All remaining arguments will be passed to the script.

"start" - Will link to the project's dirctory from you working directory (handy).

"status" - Prints a nice overview of the current situation. If the name of at least one project or category is provided, it will print more detailed information about that particular project(s) or categor(y|ies).

"stop" - Will remove the link to the project's dirctory from you working directory.

"todo" - Will open the "TODO" file in your preferred text editor.

"undone" - Just like redo, it will unarchive an archived project, but will remove the archive as if you had never archived it in the first place.

"version" or just "v" - Will spit its version information.

In every other case, if anything else is entered in the place of the verb, the script will complain printing the standard help message and failing.

Type "prj help" in your shell prompt to see the following help message:

Name:
	prj - A program to help you manage your projects and your chaotic home directory.
 
Usage:
	prj [help | listcategories|lsc | version|v]
	prj [redo | undone] <archive(s)>
	prj [renamecategory|rnc] <categoryname> <categoryname>
	prj [killcategory | newcategory] <categoryname(s)>
	prj [list|ls | listprojects|lsp] [<categoryname(s)>]
	prj [status|st] [<categoryname(s)>|<projectname(s)>]
	prj [find] <expression>
	prj [listarchives|lsa ] [<expression(s)>]
	prj [move|mv] <projectname> <categoryname>
	prj [read | start | stop | todo] <projectname>
	prj [rename|rn] <projectname> <projectname>
	prj [run] <projectname> <scriptname> [<scriptargument(s)]
	prj [done | fix | kill | new] <projectname(s)>