README @ 894fbbeb6e6d

-*- markdown -*-

hg-prompt
=========

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

Installing
----------

Clone the repository:

    $ hg clone http://bitbucket.org/sjl/hg-prompt/

Edit the `[extensions]` section in your `~/.hgrc` file:

    [extensions]
    prompt = (path to)/hg-prompt/prompt.py

Using the Command
-----------------

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 are only a few keywords at the moment (mostly the ones I want for myself).  If you have any suggestions for more please let me know.

* **bookmark:** the current bookmark
* **branch:** the current branch
* **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
* **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.

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) $ '

`source ~/.bashrc` after to test it out.  Make sure you're in a Mercurial repository or you won't see anything.

Questions, Comments, Suggestions
--------------------------------

The code was kind of thrown together in one night after I got tired of chaining three or four hg runs together to get what I wanted.  I'm sure it's not perfect, so if you've got a way to improve it please add an issue and let me know.