Prompt Extension
This extension is not distributed with Mercurial.
Author: Steve Losh steve@stevelosh.com
Project page: http://stevelosh.com/projects/hg-prompt/
Repository: https://hg.stevelosh.com/hg-prompt
Overview
The prompt extension adds an 'hg prompt' command to Mercurial for viewing repository information. It's designed to be used in a shell prompt.
Requirements
The prompt extension requires Python 2.5+ and (obviously) Mercurial.
Configuration
Configure your .hgrc to enable the extension by adding following lines:
[extensions] prompt = (path to)/hg-prompt/prompt.py
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" test
Keywords in curly braces can be used to output repository information:
$ hg prompt "currently on {branch}"
currently on defaultKeywords 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.
bookmark: the current bookmark (requires the bookmarks extension)
branch: the current branch
node: the (full) changeset hash of the current parent
node|short: a short form of the changeset hash of the current parent
node|merge: the (full) changeset hash of the changeset you're merging with if you're currently merging, otherwise nothing.
node|merge|short: a short form of the changeset hash of the changeset you're merging with if you're currently merging, otherwise nothing
rev: the repository-local changeset number of the current parent
rev|merge: the repository-local changeset number of the changeset you're merging with if you're currently merging, otherwise nothing
root: the full path to the root of the current repository, without a trailing slash
root|basename: the directory name of the root of the current repository. For example, if the repository is in /home/u/myrepo then this keyword would expand to myrepo.
status: ! if the repository has any changed/added/removed files, otherwise ? if it has any untracked (but not ignored) files, otherwise nothing.
task: the current task (requires the tasks extension)
update: ^ if the current parent is not the tip of the current branch, otherwise nothing. In effect, this lets you see if running hg update would do something.
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.
incoming: this keyword prints nothing on its own. If the default path contains incoming changesets the extra text will be expanded. For example: {incoming changes{incoming}} will expand to incoming changes if there are changes, or nothing otherwise.
incoming|count: the number of incoming changesets if greater than 0
outgoing: this keyword prints nothing on its own. If the current repository contains outgoing changesets (to default) the extra text will be expanded. For example: {outgoing changes{outgoing}} will expand to outgoing changes if there are changes, or nothing otherwise.
outgoing|count: the number of outgoing changesets if greater than 0
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.)