hg.stevelosh.com > docs.stevelosh.com

<!DOCTYPE html>
<html>
    <head>
        <meta charset="utf-8"/>
        <title>Documentation / hg-prompt</title>
        <link rel="stylesheet" href="../_dmedia/tango.css"/>
        <link rel="stylesheet/less" type="text/css" href="../_dmedia/style.less"/>
        <script src="../_dmedia/less.js" type="text/javascript">
        </script>
    </head>
    <body class="content">
        <div class="wrap">
            <header><h1><a href="..">hg-prompt</a></h1></header>
                <div class="markdown">
<h1 id="documentation"><a href="">Documentation</a></h1><p>This page contains the full documentation for <code>hg-prompt</code>.</p>
<div class="toc">
<ul>
<li><a href="#usage">Usage</a></li>
<li><a href="#keywords">Keywords</a><ul>
<li><a href="#bookmark">bookmark</a></li>
<li><a href="#branch">branch</a></li>
<li><a href="#closed">closed</a></li>
<li><a href="#count">count</a></li>
<li><a href="#incoming">incoming</a></li>
<li><a href="#node">node</a></li>
<li><a href="#outgoing">outgoing</a></li>
<li><a href="#patch">patch</a></li>
<li><a href="#patches">patches</a></li>
<li><a href="#queue">queue</a></li>
<li><a href="#rev">rev</a></li>
<li><a href="#root">root</a></li>
<li><a href="#status">status</a></li>
<li><a href="#tags">tags</a></li>
<li><a href="#task">task</a></li>
<li><a href="#tip">tip</a></li>
<li><a href="#update">update</a></li>
</ul>
</li>
<li><a href="#sample-prompts">Sample Prompts</a><ul>
<li><a href="#a-basic-prompt">A Basic Prompt</a></li>
<li><a href="#a-more-compact-basic-prompt">A More Compact Basic Prompt</a></li>
</ul>
</li>
</ul></div>
<h2 id="usage">Usage</h2>
<p>The <code>hg prompt</code> command takes a single string as an argument and outputs it.
Here's a simple (and useless) example:</p>
<div class="codehilite"><pre><span/>$ hg prompt <span class="s2">"test"</span>
<span class="nb">test</span>
</pre></div>


<p>Keywords in curly braces can be used to output repository information:</p>
<div class="codehilite"><pre><span/>$ hg prompt <span class="s2">"currently on {branch}"</span>
currently on default
</pre></div>


<p>Keywords also have an extended form:</p>
<div class="codehilite"><pre><span/>{optional text{branch}more optional text}
</pre></div>


<p>This form will output the text and the expanded keyword <strong>only</strong> if the
keyword successfully expands. This can be useful for displaying extra text
only if it's applicable:</p>
<div class="codehilite"><pre><span/>$ hg prompt <span class="s2">"currently on {branch} and at {bookmark}"</span>
currently on branch default and at

$ hg prompt <span class="s2">"currently on {branch} {and at {bookmark}}"</span>
currently on branch default

$ hg bookmark my-book

$ hg prompt <span class="s2">"currently on {branch} {and at {bookmark}}"</span>
currently on branch default and at my-book
</pre></div>


<p>You can give the <code>--angle-brackets</code> option to use angle brackets for keywords
instead of curly brackets. This can come in handy when combining a simple
prompt string with more complicated shell functionality (like color
variables):</p>
<div class="codehilite"><pre><span/>$ hg prompt <span class="s2">"{currently on {branch}}"</span>
currently on default

$ hg prompt --angle-brackets <span class="s2">"&lt;currently on &lt;branch&gt;&gt;"</span>
currently on default
</pre></div>


<h2 id="keywords">Keywords</h2>
<p>There a number of keywords available.  Some of the keywords support filters.
These filters can be combined when it makes sense.  If in doubt, try it!</p>
<h3 id="bookmark"><code>bookmark</code></h3>
<p>Display the current bookmark (requires the <a href="http://mercurial.selenic.com/wiki/BookmarksExtension">bookmarks</a> extension).</p>
<h3 id="branch"><code>branch</code></h3>
<p>Display the current branch.</p>
<ul>
<li><code>|quiet</code>: Display the current branch only if it is not the default branch.</li>
</ul>
<h3 id="closed"><code>closed</code></h3>
<p>Display <code>X</code> if working on a closed branch (i.e. if committing now would reopen
the branch).</p>
<h3 id="count"><code>count</code></h3>
<p>Display the number of revisions in the given revset (the revset <code>all()</code> will be
used if none is given).</p>
<p>See <code>hg help revsets</code> for more information.</p>
<ul>
<li><code>|REVSET</code>: The revset to count.</li>
</ul>
<h3 id="incoming"><code>incoming</code></h3>
<p>Display nothing, but if the default path contains incoming changesets the extra
text will be expanded.</p>
<p>For example: <code>{incoming changes{incoming}}</code> will expand to <code>incoming changes</code> if
there are changes, otherwise nothing.</p>
<p>Checking for incoming changesets is an expensive operation, so <code>hg-prompt</code> will
cache the results in <code>.hg/prompt/cache/</code> and refresh them every 15 minutes.</p>
<ul>
<li><code>|count</code>: Display the number of incoming changesets (if greater than 0).</li>
</ul>
<h3 id="node"><code>node</code></h3>
<p>Display the (full) changeset hash of the current parent.</p>
<ul>
<li><code>|short</code>: Display the hash as the short, 12-character form.</li>
<li><code>|merge</code>: Display the hash of the changeset you're merging with.</li>
</ul>
<h3 id="outgoing"><code>outgoing</code></h3>
<p>Display nothing, but if the current repository contains outgoing changesets (to
default) the extra text will be expanded.</p>
<p>For example: <code>{outgoing changes{outgoing}}</code> will expand to <code>outgoing changes</code> if
there are changes, otherwise nothing.</p>
<p>Checking for outgoing changesets is an expensive operation, so <code>hg-prompt</code> will
cache the results in <code>.hg/prompt/cache/</code> and refresh them every 15 minutes.</p>
<ul>
<li><code>|count</code>: Display the number of outgoing changesets (if greater than 0).</li>
</ul>
<h3 id="patch"><code>patch</code></h3>
<p>Display the topmost currently-applied patch (requires the <a href="http://mercurial.selenic.com/wiki/MqExtension">mq</a> extension).</p>
<ul>
<li><code>|count</code>: Display the number of patches in the queue.</li>
<li><code>|applied</code>: Display the number of currently applied patches in the queue.</li>
<li><code>|unapplied</code>: Display the number of currently unapplied patches in the queue.</li>
<li><code>|quiet</code>: Display a number only if there are any patches in the queue.</li>
</ul>
<h3 id="patches"><code>patches</code></h3>
<p>Display a list of the current patches in the queue.  It will look like this:</p>
<div class="codehilite"><pre><span/>$ hg prompt <span class="s1">'{patches}'</span>
bottom-patch -&gt; middle-patch -&gt; top-patch
</pre></div>


<ul>
<li><code>|reverse</code>: Display the patches in reverse order (i.e. topmost first).</li>
<li><code>|hide_applied</code>: Do not display applied patches.</li>
<li><code>|hide_unapplied</code>: Do not display unapplied patches.</li>
<li><code>|join(SEP)</code>: Display <code>SEP</code> between each patch, instead of the default <code>-&gt;</code>.</li>
<li><code>|pre_applied(STRING)</code>: Display <code>STRING</code> immediately before each applied patch.  Useful for adding color codes.</li>
<li><code>|post_applied(STRING)</code>: Display <code>STRING</code> immediately after each applied patch.  Useful for resetting color codes.</li>
<li><code>|pre_unapplied(STRING)</code>: Display <code>STRING</code> immediately before each unapplied patch.  Useful for adding color codes.</li>
<li><code>|post_unapplied(STRING)</code>: Display <code>STRING</code> immediately after each unapplied patch.  Useful for resetting color codes.</li>
</ul>
<h3 id="queue"><code>queue</code></h3>
<p>Display the name of the current MQ queue.</p>
<h3 id="rev"><code>rev</code></h3>
<p>Display the repository-local changeset number of the current parent.</p>
<ul>
<li><code>|merge</code>: Display the repository-local changeset number of the changeset you're merging with.</li>
</ul>
<h3 id="root"><code>root</code></h3>
<p>Display the full path to the root of the current repository, without a trailing
slash.</p>
<ul>
<li><code>|basename</code>: Display the directory name of the root of the current repository. For example, if the repository is in <code>/home/u/myrepo</code> then this keyword would expand to <code>myrepo</code>.</li>
</ul>
<h3 id="status"><code>status</code></h3>
<p>Display <code>!</code> if the repository has any changed/added/removed files, otherwise <code>?</code>
if it has any untracked (but not ignored) files, otherwise nothing.</p>
<ul>
<li><code>|modified</code>: Display <code>!</code> if the current repository contains files that have been modified, added, removed, or deleted, otherwise nothing.</li>
<li><code>|unknown</code>: Display <code>?</code> if the current repository contains untracked files, otherwise nothing.</li>
</ul>
<h3 id="tags"><code>tags</code></h3>
<p>Display the tags of the current parent, separated by a space.</p>
<ul>
<li><code>|quiet</code>: Display the tags of the current parent, excluding the tag <code>tip</code>.</li>
<li><code>|SEP</code>: Display the tags of the current parent, separated by <code>SEP</code>.</li>
</ul>
<h3 id="task"><code>task</code></h3>
<p>Display the current task (requires the <a href="http://bitbucket.org/alu/hgtasks/wiki/Home">tasks</a> extension).</p>
<h3 id="tip"><code>tip</code></h3>
<p>Display the repository-local changeset number of the current tip.</p>
<ul>
<li><code>|node</code>: Display the (full) changeset hash of the current tip.</li>
<li><code>|short</code>: Display a short form of the changeset hash of the current tip (must be used with the <code>|node</code> filter)</li>
</ul>
<h3 id="update"><code>update</code></h3>
<p>Display <code>^</code> if the current parent is not the tip of the current branch,
otherwise nothing.  In effect, this lets you see if running <code>hg update</code> would do
something.</p>
<h2 id="sample-prompts">Sample Prompts</h2>
<p><code>hg-prompt</code> supports many keywords, but you probably don't want to use them all
at once. Which keywords you'll find useful depends on the workflow(s) you
commonly use.</p>
<p>Here are some example prompts to get you started.</p>
<h3 id="a-basic-prompt">A Basic Prompt</h3>
<p>A very simple prompt could tell you:</p>
<ul>
<li>Which named branch you're currently working on.</li>
<li>If there are any uncommitted changes in the working directory.</li>
<li>If you're at a revision that's not a branch tip (i.e. if running <code>hg update</code>
  would do something).</li>
</ul>
<p>To get a prompt like this you could add this to your <code>~/.bashrc</code> file:</p>
<div class="codehilite"><pre><span/>export PS1='\u in \w`hg prompt "{on {branch}}{status}{update}" 2&gt;/dev/null` $'
</pre></div>


<p>The result would look something like this:</p>
<div class="codehilite"><pre><span/>username in ~/src $ cd project
username in ~/src/project on feature-branch $ touch sample
username in ~/src/project on feature-branch? $ hg add sample
username in ~/src/project on feature-branch! $ hg commit -m 'Add a file.'
username in ~/src/project on feature-branch $ hg update default
username in ~/src/project on default $ hg update 0
username in ~/src/project on default^ $
</pre></div>


<p>The <code>2&gt;/dev/null</code> part of the prompt command prevents errors from showing when
you're not currently in a Mercurial repository.</p>
<p>The keywords (<code>{branch}</code>, <code>{status}</code> and <code>{update}</code>) display the relevant
information.</p>
<p>The extra text in the <code>{branch}</code> keyword will only display if a branch exists,
so you won't see the word "on" if you're not in a repository.</p>
<h3 id="a-more-compact-basic-prompt">A More Compact Basic Prompt</h3>
<p>Some people prefer a smaller, less obtrusive prompt. To get that kind of
prompt you can omit some of the less important text:</p>
<div class="codehilite"><pre><span/>export PS1='\w`hg prompt "[{branch}{status}{update}]" 2&gt;/dev/null` $'
</pre></div>


<p>That will give you something like this:</p>
<div class="codehilite"><pre><span/>~/src $ cd project
~/src/project[feature-branch] $ touch sample
~/src/project[feature-branch?] $ hg add sample
~/src/project[feature-branch!] $ hg commit -m 'Add a file.'
~/src/project[feature-branch] $ hg update default
~/src/project[default] $ hg update 0
~/src/project[default^] $
</pre></div>
                </div>
            <footer><p><i>Made by <a href="https://stevelosh.com/">Steve Losh</a>.</i></p>
<p><a href="http://rochestermade.com" title="Rochester Made"><img src="https://rochestermade.com/media/images/rochester-made-dark-on-light.png" alt="Rochester Made" title="Rochester Made"/></a></p></footer>
        </div>
    </body>
</html>
author	Steve Losh <steve@stevelosh.com>
date	Wed, 08 Feb 2023 21:41:35 -0500
parents	9419dfa1bff9
children	(none)