Add git-heads

[git-utils.git] / git-heads.1

diff --git a/git-heads.1 b/git-heads.1
new file mode 100644 (file)
index 0000000..eb2980f
--- /dev/null
+++ b/git-heads.1
@@ -0,0 +1,111 @@
+.TH "GIT\-HEADS" "1" "" "GIT\-HEADS(1)" ""
+.SH NAME
+.PP
+git\-heads \[en] show branches without any child commits with
+\f[C]git\-log\f[](1)
+.SH SYNOPSIS
+.PP
+\f[C]git\-heads\f[] [\f[C]\-\-all\f[] | \f[C]\-\-local\f[] |
+\f[C]\-\-remote\f[]] [\f[C]\-\-branches\f[]] [(\f[C]\-\-contains\f[] |
+\f[C]\-\-merged\f[] | \f[C]\-\-no\-merged\f[]) [\f[I]commit\f[]]]
+[\f[I]git\-log\-option\f[]]\&...
+.PP
+\f[C]git\-heads\f[] [\f[C]\-\-all\f[] | \f[C]\-\-local\f[] |
+\f[C]\-\-remote\f[]] [\f[C]\-\-heads\f[]]
+[\f[I]git\-log\-option\f[]]\&...
+.SH DESCRIPTION
+.PP
+Inspired by Mercurial's \f[C]heads\f[] command this Git command's
+purpose is to display information about so\-called \[lq]heads\[rq].
+Heads are commits which have no child commits.
+This also means that they are branches that have not been merged with
+any other branch.
+Do not confuse this definition of a head with Git's \f[C]HEAD\f[] ref
+which points to the lastly checked out commit.
+Furthermore you also must not confuse it with
+\f[C]$GIT_DIR/refs/heads\f[], the directory where the references to your
+local branches are stored.
+.PP
+\f[C]git\-heads\f[]' functionality is similar to the follow programs:
+.IP
+.nf
+\f[C]
+hg\ heads
+git\ branch\ ...\ |\ xargs\ \-n1\ git\ log\ ...
+git\ wtf
+\f[]
+.fi
+.PP
+It uses \f[C]git\-log\f[](1) to display the commit information.
+.SH OPTIONS
+.TP
+.B \-a, \-\-all
+Show both local and remote branches which have no child commits.
+.RS
+.RE
+.TP
+.B \-b, \-\-branch, \-\-branches
+Show branches regardless whether they have child commits or not.
+Similar to \f[C]git\-branch\f[](1).
+.RS
+.RE
+.TP
+.B \-\-contains [\f[I]commit\f[]], \-\-merged [\f[I]commit\f[]],
+\-\-no\-merged [\f[I]commit\f[]]
+Passed to \f[C]git\-branch\f[](1).
+Implies \f[C]\-\-branches\f[].
+.RS
+.RE
+.TP
+.B \-\-head, \-\-heads
+Show only the tips of the branches without any children.
+This is the default behavior.
+.RS
+.RE
+.TP
+.B \-l, \-\-local
+Show only local branches.
+This is the default behavior.
+.RS
+.RE
+.TP
+.B \-r, \-\-remote
+Show only remote branches.
+.RS
+.RE
+.TP
+.B \f[I]git\-log\-option\f[]
+These options are passed to \f[C]git\-log\f[](1) which is used to
+display the matching branches.
+.RS
+.RE
+.SH EXAMPLES
+.PP
+Show the last five commits for every remote branch which has been merged
+with the current branch:
+.IP
+.nf
+\f[C]
+git\ heads\ \-\-remote\ \-\-branches\ \-\-merged\ \-\-format=oneline\ \-n\ 5
+\f[]
+.fi
+.PP
+Show the last three commits on every head in a graph:
+.IP
+.nf
+\f[C]
+git\ heads\ \-\-all\ \-\-graph\ \-n\ 3
+\f[]
+.fi
+.SH SEE ALSO
+.PP
+\f[C]git\f[](1), \f[C]git\-branch\f[](1), \f[C]git\-log\f[](1),
+\f[C]git\ wtf\ \-h\f[], \f[C]hg\ heads\ \-\-help\f[].
+.PP
+Homepage: <http://github.com/seschwar/git-heads>
+.SH BUGS
+.PP
+If you find a bug please report it at
+<http://github.com/seschwar/git-heads/issues>.
+.SH AUTHORS
+Sebastian Schwarz <seschwar@googlemail.com>.