docs/wiki/documentation/keywords/index.mdown @ 8ca1c9929313

Keywords
========

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

[issues]: http://bitbucket.org/sjl/issues

Some of the keywords support filters.  These filters can be combined when it makes sense.  If in doubt, try it!

[TOC]

##bookmark##
:   Display the current bookmark (requires the [bookmarks][] extension).

##branch##
:   Display the current branch.
    
    |quiet
    :   Display the current branch only if it is not the default branch.

##incoming##
:   Display nothing, but 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, otherwise nothing.
    
    Checking for incoming changesets is an expensive operation, so `hg-prompt` 
    will cache the results in `.hg/prompt/cache/` and refresh them every 15 
    minutes.
    
    |count
    :   Display the number of incoming changesets (if greater than 0).

##node##
:   Display the (full) changeset hash of the current parent.
    
    |short
    :   Display the hash as the short, 12-character form.
    
    |merge
    :   Display the hash of the changeset you're merging with.

##outgoing##
:   Display nothing, but 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, otherwise nothing.
    
    Checking for outgoing changesets is an expensive operation, so `hg-prompt` 
    will cache the results in `.hg/prompt/cache/` and refresh them every 15 
    minutes.
    
    |count
    :   Display the number of outgoing changesets (if greater than 0).

##patch##
:   Display the topmost currently-applied patch (requires the [mq][]
    extension).
    
    |count
    :   Display the number of patches in the queue.
    
    |applied
    :   Display the number of currently applied patches in the queue.
    
    |unapplied
    :   Display the number of currently unapplied patches in the queue.
    
    |quiet
    :   Display a number only if there are any patches in the queue.

##patches##
:   Display a list of the current patches in the queue.  It will look like
    this:
        
        :::console
        $ hg prompt '{patches}'
        bottom-patch -> middle-patch -> top-patch
    
    |reverse
    :   Display the patches in reverse order (i.e. topmost first).
    
    |hide_applied
    :   Do not display applied patches.
    
    |hide_unapplied
    :   Do not display unapplied patches.
    
    |join(SEP)
    :   Display SEP between each patch, instead of the default ` -> `.
    
    |pre_applied(STRING)
    :   Display STRING immediately before each applied patch.  Useful for
        adding color codes.
    
    |post_applied(STRING)
    :   Display STRING immediately after each applied patch.  Useful for
        resetting color codes.
    
    |pre_unapplied(STRING)
    :   Display STRING immediately before each unapplied patch.  Useful for
        adding color codes.
    
    |post_unapplied(STRING)
    :   Display STRING immediately after each unapplied patch.  Useful for
        resetting color codes.

##rev##
:   Display the repository-local changeset number of the current parent.
    
    |merge
    :   Display the repository-local changeset number of the changeset you're
        merging with.

##root##
:   Display the full path to the root of the current repository, without a 
    trailing slash.
    
    |basename
    :   Display 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##
:   Display `!` if the repository has any changed/added/removed files, 
    otherwise `?` if it has any untracked (but not ignored) files, otherwise 
    nothing.
    
    |modified
    :   Display `!` if the current repository contains files that have been 
        modified, added, removed, or deleted, otherwise nothing.
        
    |unknown
    :   Display `?` if the current repository contains untracked files, 
        otherwise nothing.

##tags##
:   Display the tags of the current parent, separated by a space.
    
    |SEP
    :   Display the tags of the current parent, separated by `SEP`.

##task##
:   Display the current task (requires the [tasks][] extension).

##tip##
:   Display the repository-local changeset number of the current tip.
    
    |node
    :   Display the (full) changeset hash of the current tip.
    
    |short
    :   Display a short form of the changeset hash of the current tip (must be 
        used with the **|node** filter)

##update##
:   Display `^` 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.

[bookmarks]: http://mercurial.selenic.com/wiki/BookmarksExtension
[tasks]: http://bitbucket.org/alu/hgtasks/wiki/Home
[mq]: http://mercurial.selenic.com/wiki/MqExtension