prwdrc - Man Page

The prwdrc file describes the template and various attributes affecting the behavior of prwd. The configuration file has the following format:

Empty lines and lines starting with `#' are comments, otherwise a line is of the format ``keyword arguments...''. Configuration arguments may be separated by whitespace. Arguments may optionally be enclosed in double quotes (") in order to represent arguments containing spaces.

The possible keywords and their meanings are as follows:

alias [name] [path]

Defines a new alias which could be used as a path shortener (see path in the Template Commands section) and as a shortcut (see prwd(1) and its -a parameter). The name defines the short key used as replacement to the path. See the Aliases section below for a more complete description.

set [key] [value]

Sets the global configuration parameter key to value. See the Global Settings section below for a complete list of settings and their impact on prwd.

template [value]

Defines your shell prompt template. See the section below.

prwdrc has a simple templating language with a few small commands providing basic information about your shell context. All the commands start with ``${`` and end with ``}'', within these brackets the syntax uses flags and is very similar to standard UNIX tools.

Here is a simple template definition:

template "${path -l 20}> "

This simple template returns your current path, up to 20 characters and a static "> " suffix.

The following commands available to customize your shell prompt:

path [-nc] [-l length] [-f filler]

Returns the current path (similar to the pwd command). The command-line options are as follows:

-n

Return the current path using a USENET/newsgroup-style naming convention, i.e. only use the first letters of each path component.

-c

Attempt to keep all the path components intact (cut at the slash).

-l length

Length of the final path output, including any possibly ellipsis/filler. Default: 24

-f filler

String to use as ellipsis/filler on trimmed paths. Default: "..."

branch

Display the current branch if you happen to be in a mercurial or git repository.

date [format]

Returns the current date/time using the provided format. See strftime(3) for more information on the format.

hostname [-l]

Returns the current short hostname (up until the first dot). If the -l parameters is given, this command returns the long hostname.

uid

Returns the ``$'' character if the user has UID != 0 and ``#'' otherwise. This is typically used at the end of a template, just before the trailing space.

sep [value]

Define an optional separator. If the token immediately before the sep command is empty, the value of the separator is not returned. This is useful on prompts featuring some items that could be empty from time to time (e.g. branch).

If you use the path command in your prompt, defining aliases will allow path to shorten the paths using your own defined keywords. For example:

alias *prwd /home/tamentis/projects/prwd

If you are in "/home/tamentis/projects/prwd/doc/html/", prwd would return "*prwd/doc/html". If you have spaces in your directories, you can wrap your path parameters with double quotes:

alias windocs "/mnt/Windows XP/My Documents/"

You can define multiple values for a single alias, prwd will pick the one with an existing path. This allows you to share your configuration on different machines and use the same shortened alias, for example:

alias *prwd /home/tamentis/projects/prwd
alias *prwd /Users/tamentis/projects/prwd

Aliases can be nested if you have a complicated directory hierarchy.

alias *prwd /home/tamentis/projects/prwd
alias *prwddoc *prwd/doc

Since you already define your aliases in your prwdrc file, you might want to use them in your shell. If you prefix your aliases with a '$' and add the following line to your .profile, you will be able to have your aliases available as environment variables. Add this to your profile or shell configuration file:

eval `prwd -a`

Then use your aliases like any environment variable:

cd $py3k

Note that ~ is a default alias for prwd.

Settings are defined with the set command, the first argument is the name of the setting, the second is the value:

set maxlength [length]

This setting is deprecated and was replaced by the -l parameter of the path command. If no template is defined, this will set the path length in the default template.

set filler [value]

This setting is deprecated and was replaced by the -f parameter of the path command. If no template is defined, it sets the path filler/ellipsis in the default template.

set cleancut [bool]

This setting is deprecated and was replaced by the -c parameter of the path command. If no template is defined, it sets the cleancut flag on in the default template, avoiding prwd from cutting path in the middle. For example "...rwd/doc/html" will be returned as ".../doc/html".

set newsgroup [bool]

This setting is deprecated and was replaced by the -n parameter of the path command. If no template is defined, it sets the newsgroup flag on in the default template, shortening the path by only displaying the first letter of each path components. For example "/home/tamentis/projects/prwd/src/nowhere" is turned into "/h/t/p/s/nowhere".

set mercurial [bool]

set git [bool]

This setting is deprecated and was replaced by the ${branch} command. If no template was defined, it will add the branch information between the hostname and the path in the default template.

set hostname [bool]

This setting is deprecated and was replaced by the ${hostname} command. If no template was defined, it will add the hostname information at the beginning of the default template.

set uid_indicator [bool]

This setting is deprecated and was replaced by the ${uid} command. If no template was defined, it will add the uid character at the end of the default template.

This example configuration defines two aliases and a template with the time:

alias $ports /usr/ports
alias $p /home/tamentis/projects

template "${date} ${hostname}:${branch}${sep :}${path -l 24}${uid} "

pwd(1), csh(1), ksh(1), sh(1), getcwd(3)

prwd was written by Bertrand Janin <b@janin.com> and is distributed under an ISC license (BSD compatible, OSI compatible).

prwd(1).