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

 * '''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.)

----
CategoryExtensionsByOthers