-- markdown --

About __hg_ps1

__hg_ps1 is a shell prompt helper for Mercurial repositories, similar to __git_ps1. It is intended to be called from your custom prompt string (PS1 in bash and related shells). If your working directory is in a repository, it prints the current branch name, and appends either a '!' if there are modified files in the working directory, a '?' if there are untracked files, or nothing if the repository is clean.

For example:

~/repo$ hg st
A .hgignore
~/repo$ PS1='$(__hg_ps1)\n'$PS1
on default!                       # PS1 calls __hg_ps1

__hg_ps1 is a pure Python implementation. Shell-based solutions like the one Steve Losh published start multiple Python interpreters every time the prompt is printed; this implementation only needs to run one interpreter.

Bash version

Refer to A Guide to Branching in Mercurial.

Minor tweak should be done before using the embedded hg commands.

Pros. : escape from dependency of mercurial lib in python.

Cons. : still slow, since it will invoke hg commands directly.

A little trick: use "test -e '.hg'" before generating PS1 phrases.


To install, run the setup script:

python setup.py install

This will install the source as an egg in your Python site-packages directory, and put __hg_ps1 into (most likely) /usr/local/bin. (Run python setup.py install --help for more options.)

Be sure to run setup.py with the same version of Python that Mercurial uses. On Mac OS X Leopard, to use __hg_ps1 with the version of Mercurial from http://mercurial.berkwood.com/, use /usr/bin/python, as follows:

$ /usr/bin/python setup.py [command]

This shouldn't be a concern unless you have multiple Python interpreters installed (e.g. through Fink or MacPorts).

Thanks to Jannis Leidel jannis@leidel.info for creating the setup script and reworking the code into module form.

Setting your prompt

You can then add it into your prompt string. In bash, for example, you might set the following in ~/.bashrc:

# ~/.bashrc

If you already have a custom prompt string, add the above line after it--don't replace it. For example:

# ~/.bashrc
PS1='\u@\h \w\$ '

Co-exist with __git_ps1

Example below:

# git/hg branch prompt
export PS1="[$GREEN\u$DEFAULT@\h in \w"'$(__git_ps1 " (GIT:$YELLOW%s$DEFAULT)")'""'$(~/__hg_ps1 " (HG:\033[35;40m%s \033[33;40m%s\033[37;0m)")'"]\n\$ "

Bash version below:

source ~/path/to/hg_ps1/hg_ps1.sh
export PS1="[$GREEN\u$DEFAULT@\h in \w"'$(__git_ps1 " (GIT:$YELLOW%s$DEFAULT)")''$(__hg_ps1)'"]\n\$ "