From: "Philip Oakley" <philipoakley@iee.org>
To: "Jacob Keller" <jacob.keller@gmail.com>
Cc: "GitList" <git@vger.kernel.org>,
"Junio C Hamano" <gitster@pobox.com>,
"Johannes Schindelin" <johannes.schindelin@gmx.de>
Subject: Re: [PATCH] doc: show usage of branch description
Date: Mon, 14 Sep 2015 13:01:00 +0100 [thread overview]
Message-ID: <DDA818BA5B3749C8953193DEC3682293@PhilipOakley> (raw)
In-Reply-To: CA+P7+xqh0e+2aMZf8i-1hBc0fMgaz0UjVdboLv+L9+rBYBR85w@mail.gmail.com
From: "Jacob Keller" <jacob.keller@gmail.com>
> 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.
>
> 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.
next prev parent reply other threads:[~2015-09-14 12:00 UTC|newest]
Thread overview: 57+ messages / expand[flat|nested] mbox.gz Atom feed top
2015-09-10 16:28 storing cover letter of a patch series? Jacob Keller
2015-09-10 17:41 ` Junio C Hamano
2015-09-10 18:02 ` Martin Fick
2015-09-10 18:38 ` Jacob Keller
2015-09-10 18:39 ` Junio C Hamano
2015-09-11 22:24 ` Junio C Hamano
2016-08-04 23:49 ` Michael S. Tsirkin
2016-08-05 15:39 ` Junio C Hamano
2016-08-05 21:20 ` Martin Fick
2016-08-05 21:23 ` Junio C Hamano
2016-08-06 16:51 ` Junio C Hamano
2016-08-07 5:12 ` Michael S. Tsirkin
2016-08-07 9:52 ` John Keeping
2016-08-07 10:42 ` Duy Nguyen
2016-08-08 17:42 ` Junio C Hamano
2016-08-09 7:12 ` Michael J Gruber
2015-09-10 18:32 ` Jacob Keller
2015-09-10 18:44 ` Junio C Hamano
2015-09-10 18:46 ` Jacob Keller
2015-09-10 20:09 ` Philip Oakley
2015-09-10 21:03 ` Jacob Keller
2016-08-04 23:43 ` Michael S. Tsirkin
2015-09-10 18:58 ` Johannes Schindelin
2015-09-10 21:00 ` Jacob Keller
2015-09-10 21:21 ` Johannes Schindelin
2015-09-10 22:20 ` Philip Oakley
2015-09-12 22:51 ` [PATCH] doc: show usage of branch description Philip Oakley
2015-09-12 23:44 ` Jacob Keller
2015-09-14 12:01 ` Philip Oakley [this message]
2015-09-14 13:24 ` Philip Oakley
2015-09-14 17:00 ` Junio C Hamano
2015-09-15 16:06 ` Philip Oakley
2015-09-15 19:10 ` Philip Oakley
2015-09-14 14:10 ` [PATCH v2] " Philip Oakley
2015-09-11 8:30 ` storing cover letter of a patch series? Chris Packham
2015-09-18 4:03 ` Simon Glass
2016-08-08 17:27 ` Stefan Beller
2016-08-08 20:09 ` Junio C Hamano
2016-08-13 8:49 ` Duy Nguyen
2016-08-14 7:15 ` Jacob Keller
2016-08-15 6:28 ` Stefan Beller
2016-08-15 6:38 ` Jacob Keller
2016-08-15 6:49 ` Stefan Beller
2016-08-15 6:52 ` Jacob Keller
2016-08-15 9:40 ` Duy Nguyen
2016-08-15 12:37 ` Philip Oakley
2016-08-15 13:30 ` Duy Nguyen
2016-08-15 13:47 ` John Keeping
2016-08-15 20:09 ` Jacob Keller
2016-08-15 20:38 ` Junio C Hamano
2016-08-15 23:01 ` Jacob Keller
2016-08-15 20:46 ` Philip Oakley
2016-08-16 3:45 ` Duy Nguyen
2016-08-16 5:26 ` Jacob Keller
2016-08-16 6:45 ` Duy Nguyen
2016-08-16 15:52 ` Jacob Keller
2016-08-16 21:29 ` Philip Oakley
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=DDA818BA5B3749C8953193DEC3682293@PhilipOakley \
--to=philipoakley@iee.org \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jacob.keller@gmail.com \
--cc=johannes.schindelin@gmx.de \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.