# [PATCH v2 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..." 8 messages from 2017-03-21 to 2017-03-21. Participants: Ævar Arnfjörð Bjarmason, SZEDER Gábor, Junio C Hamano. Thread: https://gitlist.dev/t/45454 ## Ævar Arnfjörð Bjarmason, 2017-03-21 14:21 Subject: [PATCH v2 1/2] doc/SubmittingPatches: clarify the casing convention for "area: change..." Message-ID: <20170321142154.16993-2-avarab@gmail.com> URL: https://gitlist.dev/e/20170321142154.16993-2-avarab%40gmail.com In-Reply-To: <20170321142154.16993-1-avarab@gmail.com> ``` Amend the section which describes how the first line of the subject should look like to say that the ":" in "area: " shouldn't be treated like a full stop for the purposes of letter casing. Change the two subject examples to make this new paragraph clearer, i.e. "unstar" is not a common word, and "git-cherry-pick.txt" is a much longer string than "githooks.txt". Pick two recent commits from git.git that fit better for the description. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/SubmittingPatches | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 3faf7eb884..9ef624ce38 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -98,12 +98,17 @@ should skip the full stop. It is also conventional in most cases to prefix the first line with "area: " where the area is a filename or identifier for the general area of the code being modified, e.g. - . archive: ustar header checksum is computed unsigned - . git-cherry-pick.txt: clarify the use of revision range notation + . doc: clarify distinction between sign-off and pgp-signing + . githooks.txt: improve the intro section If in doubt which identifier to use, run "git log --no-merges" on the files you are modifying to see the current conventions. +It's customary to start the remainder of the first line after "area: " +with a lower-case letter. E.g. "doc: clarify...", not "doc: +Clarify...", or "githooks.txt: improve...", not "githooks.txt: +Improve...". + The body should provide a meaningful commit message, which: . explains the problem the change tries to solve, iow, what is wrong -- 2.11.0 ``` ## Ævar Arnfjörð Bjarmason, 2017-03-21 14:21 Subject: [PATCH v2 2/2] doc/SubmittingPatches: show how to get a CLI commit summary Message-ID: <20170321142154.16993-3-avarab@gmail.com> URL: https://gitlist.dev/e/20170321142154.16993-3-avarab%40gmail.com In-Reply-To: <20170321142154.16993-1-avarab@gmail.com> ``` Amend the section which describes how to get a commit summary to show how do to that with "git show", currently the documentation only shows how to do that with gitk. Signed-off-by: Ævar Arnfjörð Bjarmason --- Documentation/SubmittingPatches | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches index 9ef624ce38..d8c88153c1 100644 --- a/Documentation/SubmittingPatches +++ b/Documentation/SubmittingPatches @@ -134,8 +134,17 @@ with the subject enclosed in a pair of double-quotes, like this: noticed that ... The "Copy commit summary" command of gitk can be used to obtain this -format. +format, or this invocation of "git show": + git show -s --date=short --pretty='format:%h ("%s", %ad)' + +To turn that into a handy alias: + + git config --global alias.git-commit-summary "show -s --date=short --pretty='format:%h (\"%s\", %ad)'" + +And then to get the commit summary: + + git git-commit-summary (3) Generate your patch using Git tools out of your commits. -- 2.11.0 ``` ## Ævar Arnfjörð Bjarmason, 2017-03-21 14:21 Subject: [PATCH v2 0/2] A couple of minor improvements Message-ID: <20170321142154.16993-1-avarab@gmail.com> URL: https://gitlist.dev/e/20170321142154.16993-1-avarab%40gmail.com In-Reply-To: ``` Unchanged from v1 in my <20170318184203.16890-1-avarab@gmail.com>, except 2/2 changes the "show" command to use --date=short as Junio suggested in . Ævar Arnfjörð Bjarmason (2): doc/SubmittingPatches: clarify the casing convention for "area: change..." doc/SubmittingPatches: show how to get a CLI commit summary Documentation/SubmittingPatches | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) -- 2.11.0 ``` ## SZEDER Gábor, 2017-03-21 15:51 Subject: Re: [PATCH v2 2/2] doc/SubmittingPatches: show how to get a CLI commit summary Message-ID: <20170321155153.20753-1-szeder.dev@gmail.com> URL: https://gitlist.dev/e/20170321155153.20753-1-szeder.dev%40gmail.com In-Reply-To: <20170321142154.16993-3-avarab@gmail.com> ``` > Amend the section which describes how to get a commit summary to show > how do to that with "git show", currently the documentation only shows > how to do that with gitk. > > Signed-off-by: Ævar Arnfjörð Bjarmason > --- > Documentation/SubmittingPatches | 11 ++++++++++- > 1 file changed, 10 insertions(+), 1 deletion(-) > > diff --git a/Documentation/SubmittingPatches b/Documentation/SubmittingPatches > index 9ef624ce38..d8c88153c1 100644 > --- a/Documentation/SubmittingPatches > +++ b/Documentation/SubmittingPatches > @@ -134,8 +134,17 @@ with the subject enclosed in a pair of double-quotes, like this: > noticed that ... > > The "Copy commit summary" command of gitk can be used to obtain this > -format. > +format, or this invocation of "git show": > > + git show -s --date=short --pretty='format:%h ("%s", %ad)' > + > +To turn that into a handy alias: > + > + git config --global alias.git-commit-summary "show -s --date=short --pretty='format:%h (\"%s\", %ad)'" > + > +And then to get the commit summary: > + > + git git-commit-summary - 'tformat:' is a better fit than 'format:' in this case, because it adds a trailing newline. - I actually have a pretty format alias exactly for this purpose: pretty.commitref=tformat:%h (%s, %as) and a shorter 'git log -1 --pretty=commitref ' does the trick. Perhaps it would be worth to provide this as a builtin pretty format. (Of course this relies on '%as' being interpreted as short author date to make the format work on its own, without the additional '--date=short'. Alas, git doesn't support this, see [1]. If only there were a pretty format specifier for suppressing diff output, then the '-s' could go away as well.) - I find that the two subsequent 'git's in 'git git-' look strange. However, to make this point moot right away: - I don't think SubmittingPatches is the right place to show how to create and use a command alias. [1] - http://public-inbox.org/git/1444235305-8718-1-git-send-email-szeder@ira.uka.de/T/#u ``` ## Junio C Hamano, 2017-03-21 17:58 Subject: Re: [PATCH v2 2/2] doc/SubmittingPatches: show how to get a CLI commit summary Message-ID: URL: https://gitlist.dev/e/xmqqvar2qzof.fsf%40gitster.mtv.corp.google.com In-Reply-To: <20170321155153.20753-1-szeder.dev@gmail.com> ``` SZEDER Gábor writes: >> The "Copy commit summary" command of gitk can be used to obtain this >> -format. >> +format, or this invocation of "git show": >> >> + git show -s --date=short --pretty='format:%h ("%s", %ad)' >> + >> +To turn that into a handy alias: >> + >> + git config --global alias.git-commit-summary "show -s --date=short --pretty='format:%h (\"%s\", %ad)'" >> + >> +And then to get the commit summary: >> + >> + git git-commit-summary > > - 'tformat:' is a better fit than 'format:' in this case, because it > adds a trailing newline. That depends on what you use it for. I most often use mine to insert the reference that flows in a sentence, not as a separate displayed material, e.g. 1f6b1afe ("Git 2.12.1", 2017-03-20) so for that purpose, not adding a trailing newline is a feature. > - I find that the two subsequent 'git's in 'git git-' look > strange. However, to make this point moot right away: > > - I don't think SubmittingPatches is the right place to show how to > create and use a command alias. These two I do agree with. ``` ## Ævar Arnfjörð Bjarmason, 2017-03-21 18:47 Subject: Re: [PATCH v2 2/2] doc/SubmittingPatches: show how to get a CLI commit summary Message-ID: URL: https://gitlist.dev/e/CACBZZX5ofE-B0AE1gDVwN%3DN3g-x%2Bm%3DOW72BYxK8Oz7FUkBNP7Q%40mail.gmail.com In-Reply-To: ``` On Tue, Mar 21, 2017 at 6:58 PM, Junio C Hamano wrote: > SZEDER Gábor writes: > >>> The "Copy commit summary" command of gitk can be used to obtain this >>> -format. >>> +format, or this invocation of "git show": >>> >>> + git show -s --date=short --pretty='format:%h ("%s", %ad)' >>> + >>> +To turn that into a handy alias: >>> + >>> + git config --global alias.git-commit-summary "show -s --date=short --pretty='format:%h (\"%s\", %ad)'" >>> + >>> +And then to get the commit summary: >>> + >>> + git git-commit-summary >> >> - 'tformat:' is a better fit than 'format:' in this case, because it >> adds a trailing newline. > > That depends on what you use it for. I most often use mine to > insert the reference that flows in a sentence, not as a separate > displayed material, e.g. > > 1f6b1afe ("Git 2.12.1", 2017-03-20) > > so for that purpose, not adding a trailing newline is a feature. I agree with tformat. I didn't notice this because I've been screwing around with my pager settings and my configuration was implicitly adding a newline. Do you mind fixing that up Junio, or should I re-send it? >> - I find that the two subsequent 'git's in 'git git-' look >> strange. However, to make this point moot right away: >> >> - I don't think SubmittingPatches is the right place to show how to >> create and use a command alias. > > These two I do agree with. I don't think it disturbs the flow of the document, and since someone going through SubmittingPatches is likely about to submit a patch, providing that one-liner is handy, not as some "here's how to add aliases" tutorial, but so you don't need to go and copy/paste it, add \'s for the "'s etc. ``` ## SZEDER Gábor, 2017-03-21 20:01 Subject: Re: [PATCH v2 2/2] doc/SubmittingPatches: show how to get a CLI commit summary Message-ID: URL: https://gitlist.dev/e/CAM0VKjmZS-mTdtBb1BDhixzWMou7h7VZSo3hpj5pk_C6i_MBnA%40mail.gmail.com In-Reply-To: ``` On Tue, Mar 21, 2017 at 6:58 PM, Junio C Hamano wrote: > SZEDER Gábor writes: > >>> The "Copy commit summary" command of gitk can be used to obtain this >>> -format. >>> +format, or this invocation of "git show": >>> >>> + git show -s --date=short --pretty='format:%h ("%s", %ad)' >>> + >>> +To turn that into a handy alias: >>> + >>> + git config --global alias.git-commit-summary "show -s --date=short --pretty='format:%h (\"%s\", %ad)'" >>> + >>> +And then to get the commit summary: >>> + >>> + git git-commit-summary >> >> - 'tformat:' is a better fit than 'format:' in this case, because it >> adds a trailing newline. > > That depends on what you use it for. I most often use mine to > insert the reference that flows in a sentence, not as a separate > displayed material, e.g. > > 1f6b1afe ("Git 2.12.1", 2017-03-20) > > so for that purpose, not adding a trailing newline is a feature. Perhaps we are running it differently. I use its output that way, too, usually running the command in a terminal and copy-pasting its output into an editor. For this I find 'tformat:' clearly better, because the reference ends up on its own line: it's separate from the next prompt and easy to copy the whole thing with a triple-click anywhere on that line. With 'format:' the subsequent shell prompt is the direct continuation of the reference: ~/src/git (master %)$ git show -s --date=short --pretty='format:%h ("%s", %ad)' master c0f9c7058 ("Sync with 2.12.1", 2017-03-20)~/src/git (master %)$ I don't like this, because it looks ugly, is a bit more difficult to copy, and if I press the up key for shell history, then for some reason it gets messed up like this: c0f9c7058 ("Sync with 2.12.1", 2017-03-20)~/src/git (master %)$ git show -s --da masterrt --pretty='format:%h ("%s", %ad)' m with the cursor blinking on the last line after 'master'. ``` ## Junio C Hamano, 2017-03-21 20:13 Subject: Re: [PATCH v2 2/2] doc/SubmittingPatches: show how to get a CLI commit summary Message-ID: URL: https://gitlist.dev/e/xmqqlgryo0bz.fsf%40gitster.mtv.corp.google.com In-Reply-To: ``` SZEDER Gábor writes: >> That depends on what you use it for. I most often use mine to >> insert the reference that flows in a sentence, not as a separate >> displayed material, e.g. >> >> 1f6b1afe ("Git 2.12.1", 2017-03-20) >> >> so for that purpose, not adding a trailing newline is a feature. > > Perhaps we are running it differently. > > I use its output that way, too, usually running the command in a > terminal and copy-pasting its output into an editor. I do \C-u\M-!git one from Emacs in the middle of typing a sentence (where "git one" is aliased to that --format thing), and for this I obviously do not want the terminating newline. Of course --pretty=format:... has the opposite effect and in a terminal to make it easier to cut&paste you do want to have its output separated from the prompt string. So as I said, "That depends on what you use it for." As this is a mere example, we should just shoot for brevity instead? Both "--pretty=format:" and "--pretty=tformat:" are much longer than "--format=", so we can just mention git show --date=short -s --format='%h ("%s", %ad)' and let the users to customize it for their needs? ```