v2, 2 partsdoc/SubmittingPatches: clarify the casing convention for "area: change..."

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 <xmqq37ea2ykh.fsf@gitster.mtv.corp.google.com>.

Æ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(-)

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 <avarab@gmail.com>
---
 Documentation/SubmittingPatches | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

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 <avarab@gmail.com>
---
 Documentation/SubmittingPatches | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

- '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 <commit>' 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-<whatever>' 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

SZEDER Gábor <szeder.dev@gmail.com> 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.

These two I do agree with.

On Tue, Mar 21, 2017 at 6:58 PM, Junio C Hamano <gitster@pobox.com> wrote:

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

On Tue, Mar 21, 2017 at 6:58 PM, Junio C Hamano <gitster@pobox.com> wrote:

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

SZEDER Gábor <szeder.dev@gmail.com> writes:

I do \C-u\M-!git one<ENTER> 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?