Re: [PATCH] doc: show usage of branch description
- From
Philip Oakley <philipoakley@iee.org>
- Date
- Sep 14, 2015, 12:01 UTC
- Message-ID
- <DDA818BA5B3749C8953193DEC3682293@PhilipOakley>
- In-Reply-To
- <CA+P7+xqh0e+2aMZf8i-1hBc0fMgaz0UjVdboLv+L9+rBYBR85w@mail.gmail.com>
From: "Jacob Keller" <jacob.keller@gmail.com>
Show 45 quoted lines
> Hi, > > On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley <philipoakley@iee.org> > wrote: >> The branch description will be included in 'git format-patch >> --cover-letter' and in 'git pull-request' emails. Tell the reader. >> >> While here, clarify that the description may be a multi-line >> explanation of the purpose of the branch's patch series. >> >> Signed-off-by: Philip Oakley <philipoakley@iee.org> >> --- >> >> This is a short doc patch to follow up $gmane/277628 where Johannes >> Schindelin noted this otherwise undocumented feature. >> > > Thanks for this. > >> >> Documentation/git-branch.txt | 3 ++- >> Documentation/git-format-patch.txt | 2 +- >> Documentation/git-request-pull.txt | 3 ++- >> 3 files changed, 5 insertions(+), 3 deletions(-) >> >> diff --git a/Documentation/git-branch.txt >> b/Documentation/git-branch.txt >> index a67138a..79ad1c7 100644 >> --- a/Documentation/git-branch.txt >> +++ b/Documentation/git-branch.txt >> @@ -197,7 +197,8 @@ start-point is either a local or remote-tracking >> branch. >> >> --edit-description:: >> Open an editor and edit the text to explain what the branch >> is >> - for, to be used by various other commands (e.g. >> `request-pull`). >> + for, to be used by various other commands (e.g. >> `format-patch` >> + and `request-pull`). Multi-line explanations may be used. >> > > Are these the only locations? Just want to make sure while we're > updating it.
Searching for 'description' has many hits so it's not easy to be really sure. I had thought I'd asked an SO question ($SO/q/6866838) about branch descriptions many years ago, whose answers indicated it was little used, but actually I'd asked about the repo description (doh) which AFAICT is only used by gitweb.
A bit more delving found http://stackoverflow.com/a/8858853/717355 which suggests `git merge` would use it, but with no mention in the `git merge --help` man page. A link to the `git fmt-merge-msg` ("for internal use by scripts") finally provides the extra:
merge.branchdesc
In addition to branch names, populate the log message with the branch description text associated with them. Defaults to false.
However, that config key isn't listed in `git config --help` man page, so that capability is a bit buried. (note the default!)
It still means that my patch is incomplete in its aim to bring out these possible broader usages.
I haven't yet looked at the mail archives to see if there is more around the time of those introductions.
Show 5 quoted lines
> > Otherwise, for what it's worth... > > Acked-by: Jacob Keller <jacob.keller@gmail.com> >
For the future, it would also be nice to allow some use within `git branch` for a `--show[-full]-description` option such that when branch info is being given (-a, -l, etc), then the descriptions for the local branches (which may have descriptions) are displayed, either as a single first line, or as a full multi-line description. But that's coding & review for the future.