| Message ID | 20231003082107.3002173-3-stepnem@smrk.net (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | a62a7060a50e09089fb63b793b97c4b570993142 |
| Headers | show |
| Series | [1/5] Fix some typos, grammar or wording issues in the documentation | expand |
On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote: > There's even an example of such usage in the README. > > Signed-off-by: Štěpán Němec <stepnem@smrk.net> > --- > diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump > @@ -9,7 +9,7 @@ The <mode> parameter is one of: > > diff: elements are diff hunks. Arguments are given to diff. > > -merge: elements are merge conflicts. Arguments are ignored. > +merge: elements are merge conflicts. Arguments are given to ls-files -u. Should "ls-files -u" be formatted with backticks? Arguments are passed to `git ls-files -u`.
On Tue, 3 Oct 2023 14:33:39 -0400 Eric Sunshine wrote: > On Tue, Oct 3, 2023 at 4:28 AM Štěpán Němec <stepnem@smrk.net> wrote: >> There's even an example of such usage in the README. >> >> Signed-off-by: Štěpán Němec <stepnem@smrk.net> >> --- >> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump >> @@ -9,7 +9,7 @@ The <mode> parameter is one of: >> >> diff: elements are diff hunks. Arguments are given to diff. >> >> -merge: elements are merge conflicts. Arguments are ignored. >> +merge: elements are merge conflicts. Arguments are given to ls-files -u. > > Should "ls-files -u" be formatted with backticks? > > Arguments are passed to `git ls-files -u`. My preference is against this (I don't like markup in plain-text files), although, unlike the contrib README case in 1/5, here there _are_ some pre-existing backquotes; but the usage is inconsistent. If we want to unify one way or the other, I'd leave that for another patch, in any case. Thanks, Štěpán
Eric Sunshine <sunshine@sunshineco.com> writes: >> There's even an example of such usage in the README. >> >> Signed-off-by: Štěpán Němec <stepnem@smrk.net> >> --- >> diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump >> @@ -9,7 +9,7 @@ The <mode> parameter is one of: >> >> diff: elements are diff hunks. Arguments are given to diff. >> >> -merge: elements are merge conflicts. Arguments are ignored. >> +merge: elements are merge conflicts. Arguments are given to ls-files -u. > > Should "ls-files -u" be formatted with backticks? > > Arguments are passed to `git ls-files -u`. Probably not in this case, as this is end-user visible help message that is not formatted but given to the terminal. The whole preimage looks like this: usage: git jump [--stdout] <mode> [<args>] Jump to interesting elements in an editor. The <mode> parameter is one of: diff: elements are diff hunks. Arguments are given to diff. merge: elements are merge conflicts. Arguments are ignored. grep: elements are grep hits. Arguments are given to git grep or, if configured, to the command in `jump.grepCmd`. ws: elements are whitespace errors. Arguments are given to diff --check. If the optional argument `--stdout` is given, print the quickfix lines to standard output instead of feeding it to the editor. and it is already a mixture. "given to `git grep`" is not quoted, neither is "given to `diff --check`" or "given to `diff`" I think rule for help/usage messages should be that - anything that the end-user may want to cut&paste should be left alone to make it easier to cut, - but at the same time the message should make it clear which part of a sentence is what, Clicking on `--stdout` or `jump.grepCmd` does not include the surrounding quotes, at least in my environment, so the use of backquotes in these places satisfy the two goals, it seems. Unlike `--stdout` and `jump.grepCmd`, all other things that are not quoted, including the one that is added by this patch (i.e., "ls-files -u"), are something the end-user needs to cut and paste in reaction to seeing this error message, so as long as they are understandable in the sentences they appear in, I think they are fine. If we wanted to standardize, we may start to encourage consistent use of quoting, but I do not think it should be part of this topic. Thanks for being careful and thoughtful.
Junio C Hamano <gitster@pobox.com> writes: > Unlike `--stdout` and `jump.grepCmd`, all other things that are not > quoted, including the one that is added by this patch (i.e., > "ls-files -u"), are something the end-user needs to cut and paste in "are" -> "are NOT". Sorry for the noise. > reaction to seeing this error message, so as long as they are > understandable in the sentences they appear in, I think they are > fine. > > If we wanted to standardize, we may start to encourage consistent > use of quoting, but I do not think it should be part of this topic. > > Thanks for being careful and thoughtful.
diff --git a/contrib/git-jump/git-jump b/contrib/git-jump/git-jump index 40c4b0d11107..47e0c557e63f 100755 --- a/contrib/git-jump/git-jump +++ b/contrib/git-jump/git-jump @@ -9,7 +9,7 @@ The <mode> parameter is one of: diff: elements are diff hunks. Arguments are given to diff. -merge: elements are merge conflicts. Arguments are ignored. +merge: elements are merge conflicts. Arguments are given to ls-files -u. grep: elements are grep hits. Arguments are given to git grep or, if configured, to the command in `jump.grepCmd`.
There's even an example of such usage in the README. Fixes: 67ba13e5a4b2 ("git-jump: pass "merge" arguments to ls-files") Signed-off-by: Štěpán Němec <stepnem@smrk.net> --- contrib/git-jump/git-jump | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)