Added git footers tool to parse conventional metadata from git commits

man/man1/git-footers.1

+'\" t
+.\"     Title: git-freeze
+.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
+.\"      Date: 09/02/2014
+.\"    Manual: Chromium depot_tools Manual
+.\"    Source: depot_tools c9f28eb
+.\"  Language: English
+.\"
+.TH "GIT\-FREEZE" "1" "09/02/2014" "depot_tools c9f28eb" "Chromium depot_tools Manual"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+git-footers \- Extract meta\-information expressed as footers in a commit message\&.
+.SH "SYNOPSIS"
+.sp
+.nf
+\fIgit footers\fR [\-\-key FOOTER] REF
+\fIgit footers\fR [\-\-position | \-\-position\-ref | \-\-position\-num] REF
+.fi
+.sp
+.SH "DESCRIPTION"
+.sp
+git footers extracts information included in commit messages as "footers", which are roughly like HTTP headers except they are at the end\&. For example, a commit might look like:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+This is a fancy commit message\&.
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+Cr\-Commit\-Position: refs/heads/master@{#292272}
+Tech\-Debt\-Introduced: 17 nanoMSOffices
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+git footers knows how to extract this information\&.
+.sp
+Footers are order\-independent and can appear more than once\&. Thus they are treated as a multimap\&.
+.SH "OPTIONS"
+.sp
+If no options are given, all footers are printed, with their names case\-normalized\&.
+.PP
+\-\-key FOOTER
+.RS 4
+Extract all the headers associated with the given key, and print one per line\&. If there are no footers with this key, produces no output and exits successfully\&.
+.RE
+.PP
+\-\-position
+.RS 4
+Extract the Chrome commit position from the footers\&. This first attempts to get the value of the
+Cr\-Commit\-Position
+footer\&. If that doesn\(cqt exist then it tries a heuristic based on
+Git\-Svn\-Id\&. Output is in one of the following forms:
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+refs/heads/master@{#292272}
+refs/branch\-heads/branchname
+.fi
+.if n \{\
+.RE
+.\}
+.RE
+.PP
+\-\-position\-num
+.RS 4
+Extracts and prints the Chrome commit position number only (292272 in the example above)\&. Exits with an error if one cannot be found\&.
+.RE
+.PP
+\-\-position\-ref
+.RS 4
+Extracts and prints the Chrome commit position ref name only (ref/heads/master
+or
+refs/branch\-heads/branchname
+in the example above)\&.
+.RE
+.SH "EXAMPLE"
+.sp
+
+.sp
+.if n \{\
+.RS 4
+.\}
+.nf
+\fB$ git footers HEAD\fR
+Tech\-Debt\-Introduced: \-4 microMSOffices
+Tech\-Debt\-Introduced: 17 microMSOffices
+Cr\-Commit\-Position: refs/heads/master@{#292272}
+\fB$ git footers \-\-key Tech\-Debt\-Introduced HEAD\fR
+\-4 microMSOffices
+17 microMSOffices
+\fB$ git footers \-\-position HEAD\fR
+refs/heads/master@{#292272}
+\fB$ git footers \-\-position\-num HEAD\fR
+292272
+\fB$ git footers \-\-position\-ref HEAD\fR
+refs/heads/master
+.fi
+.if n \{\
+.RE
+.\}
+.sp
+.SH "SEE ALSO"
+.sp
+\fBgit-number\fR(1)
+.SH "CHROMIUM DEPOT_TOOLS"
+.sp
+Part of the chromium \fBdepot_tools\fR(7) suite\&. These tools are meant to assist with the development of chromium and related projects\&. Download the tools from \m[blue]\fBhere\fR\m[]\&\s-2\u[1]\d\s+2\&.
+.SH "NOTES"
+.IP " 1." 4
+here
+.RS 4
+\%https://chromium.googlesource.com/chromium/tools/depot_tools.git
+.RE