README @ a62c8ab6c87f

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

Requirements
------------

hg-prompt requires Python 2.6 and makes use of some of the nifty new features.  

If you'd like to use it with Python 2.5, you'll need to add the following line at the top of the `prompt.py` file (right after the `#!/usr/bin/env python` line):

    from __future__ import with_statement

That's two underscores on each side of the word "future".

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

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
    $

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

The code was kind of thrown together in a few nights 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.