From: Philip Oakley Date: Mon, 14 Sep 2015 12:01:00 GMT Subject: Re: [PATCH] doc: show usage of branch description Message-ID: In-Reply-To: From: "Jacob Keller" > Hi, > > On Sat, Sep 12, 2015 at 3:51 PM, Philip Oakley > 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 >> --- >> >> 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. > > Otherwise, for what it's worth... > > Acked-by: Jacob Keller > 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.