The prj program is just a shell script that aims at helping you manage and organize your chaotic home directory.

You can find out how to use it by reading the documentation.

Read the f* manual!

You could learn how to use it, also, just by looking at what other interesting things people are using it for.

Peak at the usecases.

Follow the master development branch to be notifyed when something changes.

Follow the master.

If you want to help, you can read about what's in the workings on the TODO file.

What TODO?

The code of the script itself is licensed under the GPL V3 license.

Know your rights!

The content of this website, though, is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License. Which is, entirelly, a different subject.

More rights!

The “reflection” icons where taken from webdesignerdepot.com.

Even more rights!

In order to proceed with your investigation and access the download and contact pages, head over to the initial page.

Go Home!

- 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 screenshot:

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 any file called depends-<projectname> as a dependency on that project 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), 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).

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 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

Will print the categories names. Simple.

listprojects or 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 except for the working category that is always the last to be printed).

move or mv

Will move a project from one category to another.

new

Will create a new project in your firs 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 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)>

Hope this was helpfull and you can now start using the script.

In order to proceed with your investigations and access the download and contact pages, head over to the initial page.

Go Home!

Sheena is a punk rocker

She still uses the outdates 1.x series of the script, as the sloppy punk she is!

Each of her projects is a song or a subject somehow related to the production of an album and she decides to rename the script to composer. She opens up the script file in emacs and changes the values of some variables.

mv ~/prj/prj ~/bin/composer
emacs /home/sheena/bin/composer

workingdirname="Stage"
workingdirprefix="a"
doneconfiguring="Yes"

She, then, opens her ~/.config/user-dirs.dirs file and changes the name of some default locations.

emacs .config/user-dirs.dirs

XDG_DESKTOP_DIR="/home/sheena/Stage"
XDG_PROJECTS_DIR="$HOME/Garage"
XDG_BACKUPS_DIR="$HOME/Attic"

In order to host her work on the new album, she creates a category in which she will place every music that will go into that album.

composer newcategory b.NextAlbum

She, then, starts a project for each of the songs she plans to prepare for the album.

composer new LoveSongNot
composer new DoesHumourBelongInMusic
composer new MyDearBrutalDefenders
composer new AnarchyInTheUK
composer new title
composer new cover
composer new production

But she will only work on MyDearBrutalDefenders and on the title for now.

composer move LoveSongNot b
composer mv DoesHumourBelongInMusic b

And AnarchyInTheUK should, really, go into a covers only album she's been thinking about for a long time.

composer newcategory c.CoversAlbum
composer mv AnarchyInTheUK c

The cover project will be a graphics project. Only a few binary files, so no need to keep it under git revision control.

rm -fr Stage/cover/.git

The title project will be only a single text file with commented ideas, so there is no need for the trash directory or anything...

rmdir Stage/title/trash
touch Stage/title/title.org

Of course, she will keep this one under git control. :-)

$ composer ls

[CoversAlbum]
AnarchyInTheUK

[NextAlbum]
DoesHumourBelongInMusic
LoveSongNot

[Stage]
cover
MyDearBrutalDefenders
production
title

What about the title for the covers only album? She can't have two projects with the same name.

composer rename title NextAlbumTitle
composer new CoversAlbumTitle
rmdir Stage/CoversAlbumTitle/trash
touch Stage/CoversAlbumTitle/title.org
composer mv CoversAlbumTitle c
composer ls

[CoversAlbum]
CoversAlbumTitle
AnarchyInTheUK

[NextAlbum]
DoesHumourBelongInMusic
LoveSongNot

[Stage]
cover
MyDearBrutalDefenders
production
NextAlbumTitle

=:-)

In order to proceed with your investigations and access the download and contact pages, head over to the initial page.

Go Home!

If you are one of the braves, just clone the repo. That's the hard way.

git clone git://github.com/lab-rasparta-org/prj

Optionaly, download the tarbal and unpack it in a convenient place inside your home directory.

You rock!

If you are under windows, it might be more convenient to donwload the zip file.

Get the zip file instead.

You can also download just the prj script itself.
You might need to right-click the link and choose something like" Save Link As..." from the dropdown menu.
Just remember to set the permissions correctly afterwads.

chmod u+x prj

Just the main thing.

To know more about it or get in touch, head over to the main page.

Go Home!

Send an email.

The easy way.

Go straight to the GitHub project page.

The hard way.

To know more or to get it, head over to the main page.

Go Home!