Prompt Extension

This extension is not distributed with Mercurial.

Author: Steve Losh

Project page:



The prompt extension adds an 'hg prompt' command to Mercurial for viewing repository information. It's designed to be used in a shell prompt.


The prompt extension requires Python 2.5+ and (obviously) Mercurial.


Configure your .hgrc to enable the extension by adding following lines:

prompt = (path to)/hg-prompt/

Basic Usage

The hg prompt command takes a single string as an argument and outputs it. Here's a simple (and useless) example:

$ hg prompt "test"

Keywords in curly braces can be used to output repository information:

$ hg prompt "currently on {branch}"
currently on default

Keywords also have an extended form:

{optional text{branch}more optional text}

This form will output the text and the expanded keyword only if the keyword successfully expands. This can be useful for displaying extra text only if it's applicable:

$ hg prompt "currently on {branch} and at {bookmark}"
currently on branch default and at 

$ hg prompt "currently on {branch} {and at {bookmark}}"
currently on branch default 

$ hg bookmark my-book

$ hg prompt "currently on {branch} {and at {bookmark}}"
currently on branch default and at my-book

Available Keywords

There a number of keywords available. If you have any suggestions for more please let me know.

Remote Status Keywords

There are several keywords available to monitor the status of remote repositories. Because this can be an expensive operation if the remote repository is across a network, they cache their results in .hg/prompt/cache/. The cache is updated roughly every fifteen minutes.

Putting it in a Bash Prompt

To put it in your bash prompt, edit your ~/.bashrc file to include something like this:

hg_ps1() {
    hg prompt "{ on {branch}}{ at {bookmark}}{status}" 2> /dev/null

export PS1='\u at \h in \w$(hg_ps1)\n$ '

source ~/.bashrc after to test it out. Make sure you're in a Mercurial repository or you won't see anything. This little prompt will give you something like this:

steve at myhost in ~/src/hg-prompt on default at feature-bookmark?

How about something a little more interesting?

hg_ps1() {
    hg prompt "{[+{incoming|count}]-->}{root|basename}{/{branch}}{-->[+{outgoing|count}]}{ at {bookmark}}{status}" 2> /dev/null

export PS1='$(hg_ps1)\n\u at \h in \w\n$ '

And the result (this example assumes one incoming changeset and two outgoing):

[+1]-->hg-prompt/default-->[+2] at feature-bookmark
steve at myhost in ~/src/hg-prompt

The above technique causes the hg_ps1 function to be executed every time PS1 is evaluated. If you are content with hg status appearing before the prompt rather than embedded in it, it is more convenient to use PROMPT_COMMAND, like this:

# display status like "repo / branch@bookmark / f2460e250e9c / 22 [!/^/2▾/3▴]" on a line above the prompt
PROMPT_COMMAND="hg prompt '>> {root|basename} / {branch}{@ {bookmark}} / {node|short}{+{node|merge|short}} / {rev} [{status}/{update}/{incoming|count}▾/{outgoing|count}▴]' 2>/dev/null && echo"

("&& echo" causes the hg status to appear on a line by itself.)


PromptExtension (last edited 2021-12-31 17:43:22 by SamBirch)