man/html/git-footers.html - Issue 521033002: Added git footers tool to parse conventional metadata from git commits

Unified Diff: man/html/git-footers.html

Issue 521033002: Added git footers tool to parse conventional metadata from git commits (Closed) Base URL: https://chromium.googlesource.com/chromium/tools/depot_tools.git@master

Patch Set: Docs and tests Created 6 years, 3 months ago

Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.

Jump to:

View side-by-side diff with in-line comments

Download patch

Index: man/html/git-footers.html

diff --git a/man/html/git-map-branches.html b/man/html/git-footers.html

similarity index 84%

copy from man/html/git-map-branches.html

copy to man/html/git-footers.html

index e3d1d330fdd0f603460e382f254a60e10bc83b3c..11147ff28933c7385897ce5a29c68e5ae4b6ec28 100644

--- a/man/html/git-map-branches.html

+++ b/man/html/git-footers.html

@@ -4,7 +4,7 @@

<head>

-<title>git-map-branches(1)</title>

+<title>git-freeze(1)</title>

/* Shared CSS for AsciiDoc xhtml11 and html5 backends */

@@ -741,12 +741,12 @@ asciidoc.install();

<h1>

-git-map-branches(1) Manual Page

+git-freeze(1) Manual Page

</h1>

-<p>git-map-branches -

- Helper script to display all local git branches with ‘upstream’ hierarchy in colorized terminal format.

+<p>git-footers -

+ Extract meta-information expressed as footers in a commit message.

</p>

</div>

@@ -755,7 +755,8 @@ git-map-branches(1) Manual Page

<h2 id="_synopsis">SYNOPSIS</h2>

-<pre class="content"><em>git map-branches</em></pre>

+<pre class="content"><em>git footers</em> [--key FOOTER] REF

+<em>git footers</em> [--position | --position-ref | --position-num] REF</pre>

</div></div>

</div>

@@ -763,89 +764,99 @@ git-map-branches(1) Manual Page

<h2 id="_description">DESCRIPTION</h2>

-<div class="paragraph"><p>Git map-branches displays all local branches such that:</p></div>

-<div class="ulist"><ul>

-<li>

-<p>

-Current branch is <span class="aqua">cyan</span>.

-</p>

-<div class="ulist"><ul>

-<li>

-<p>

-The branch which will be modified with git-commit is denoted with an asterisk

- (<code>*</code>) after the name.

-</p>

-</li>

-</ul></div>

-</li>

-<li>

+<div class="paragraph"><p><code>git footers</code> 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:</p></div>

+<div class="literalblock">

+<div class="content">

+<pre><code>This is a fancy commit message.</code></pre>

+</div></div>

+<div class="literalblock">

+<div class="content">

+<pre><code>Cr-Commit-Position: refs/heads/master@{#292272}

+Tech-Debt-Introduced: 17 nanoMSOffices</code></pre>

+</div></div>

+<div class="paragraph"><p><code>git footers</code> knows how to extract this information.</p></div>

+<div class="paragraph"><p>Footers are order-independent and can appear more than once. Thus they are

+treated as a multimap.</p></div>

+</div>

+<div class="sect1">

+<h2 id="_options">OPTIONS</h2>

+<div class="sectionbody">

+<div class="paragraph"><p>If no options are given, all footers are printed, with their names

+case-normalized.</p></div>

+<div class="dlist"><dl>

+<dt class="hdlist1">

+--key FOOTER

+</dt>

+<dd>

<p>

-Local branches are <span class="green">green</span>.

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

</p>

-</li>

-<li>

+</dd>

+<dt class="hdlist1">

+--position

+</dt>

+<dd>

<p>

-Remote branches are <span class="red">red</span> (usually, the root of all other branches).

+ Extract the Chrome commit position from the footers. This first attempts

+ to get the value of the <code>Cr-Commit-Position</code> footer. If that doesn’t exist

+ then it tries a heuristic based on <code>Git-Svn-Id</code>. Output is in one of the

+ following forms:

</p>

-</li>

-<li>

+<div class="literalblock">

+<div class="content">

+<pre><code>refs/heads/master@{#292272}

+refs/branch-heads/branchname</code></pre>

+</div></div>

+</dd>

+<dt class="hdlist1">

+--position-num

+</dt>

+<dd>

<p>

-<code>{NO UPSTREAM}</code> is a special placeholder in <span class="fuchsia">magenta</span>.

+ Extracts and prints the Chrome commit position number only (292272 in the

+ example above). Exits with an error if one cannot be found.

</p>

-<div class="ulist"><ul>

-<li>

+</dd>

+<dt class="hdlist1">

+--position-ref

+</dt>

+<dd>

<p>

-Branches which have this as their parent are usually misconfigured, and

- should be assigned a parent by checking out the branch and running git branch

- --set-upstream-to=<correct parent branch>.

+ Extracts and prints the Chrome commit position ref name only

+ (<code>ref/heads/master</code> or <code>refs/branch-heads/branchname</code> in the example above).

</p>

-</li>

-</ul></div>

-</li>

-</ul></div>

-<div class="admonitionblock">

-<table><tr>

-<td class="icon">

-<div class="title">Note</div>

-</td>

-<td class="content">If multiple branches are on the same commit, they will all be cyan.</td>

-</tr></table>

-</div>

+</dd>

+</dl></div>

</div>

<h2 id="_example">EXAMPLE</h2>

-<div class="paragraph"><p>Given the hypothetical demo repo in <a href="git-map.html">git-map(1)</a>'s EXAMPLE section, and

-assuming that the <code>frozen_changes</code> branch was currently checked out, running

-<em>git map-branches</em> would result in an output like:</p></div>

-<div class="paragraph"><p></p></div><div class="listingblock"><div class="content"><pre><code><span style="font-weight: bold; color: #ffffff">$ git map-branches</span>

-<span style="color: #e42e16"></span><span style="color: #e42e16">origin/master

-</span><span style="color: #19c518"></span><span style="color: #19c518"> cool_feature

-</span><span style="color: #19c518"></span><span style="color: #19c518"> subfeature

-</span><span style="color: #19c518"></span><span style="color: #19c518"> fixit

-</span><span style="color: #33d6e5"></span><span style="font-weight: bold; color: #33d6e5"> frozen_branch *

-</span><span style="font-weight: bold; color: #d338d3"></span><span style="color: #d338d3">{NO UPSTREAM}

-</span><span style="color: #19c518"></span><span style="color: #19c518"> no_upstream</span>

+<div class="paragraph"><p></p></div><div class="listingblock"><div class="content"><pre><code><span style="font-weight: bold; color: #ffffff">$ git footers HEAD</span>

+Tech-Debt-Introduced: -4 microMSOffices

+Tech-Debt-Introduced: 17 microMSOffices

+Cr-Commit-Position: refs/heads/master@{#292272}

+<span style="font-weight: bold; color: #ffffff">$ git footers --key Tech-Debt-Introduced HEAD</span>

+-4 microMSOffices

+17 microMSOffices

+<span style="font-weight: bold; color: #ffffff">$ git footers --position HEAD</span>

+refs/heads/master@{#292272}

+<span style="font-weight: bold; color: #ffffff">$ git footers --position-num HEAD</span>

+292272

+<span style="font-weight: bold; color: #ffffff">$ git footers --position-ref HEAD</span>

+refs/heads/master

</code></pre></div></div><p><div class="paragraph"></p></div>

</div>

-<h2 id="_suggested_aliases">SUGGESTED ALIASES</h2>

-<div class="sectionbody">

-<div class="paragraph"><p>Some common short-hand aliases. Feel free to add these to your <em>~/.gitconfig</em>

-file.</p></div>

-<div class="listingblock">

-<div class="content">

-<pre><code>[alias]

- git bmap = map-branches</code></pre>

-</div></div>

-</div>

-<div class="sect1">

-<div class="paragraph"><p><a href="git-map.html">git-map(1)</a></p></div>

+<div class="paragraph"><p><a href="git-number.html">git-number(1)</a></p></div>

</div>

@@ -860,7 +871,7 @@ from <a href="https://chromium.googlesource.com/chromium/tools/depot_tools.git">

-Last updated 2014-04-10 14:23:11 PDT

+Last updated 2014-09-02 16:59:41 PDT

</div>

</body>

« git_footers.py ('K') | « git_footers.py ('k') | man/man1/git-footers.1 » ('j') | man/src/git-footers.demo.1.sh » ('J')