hg-prompt/full-documentation/index.html @ 0f6bab39c0f4
default tip
adopt: Update site.
author |
Steve Losh <steve@stevelosh.com> |
date |
Thu, 13 Jun 2024 13:05:28 -0400 |
parents |
9419dfa1bff9 |
children |
(none) |
<!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">"<currently on <branch>>"</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 -> middle-patch -> 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>-></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>/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>/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>/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>