git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
From: Philippe Blain <levraiphilippeblain@gmail.com>
To: "Ævar Arnfjörð Bjarmason" <avarab@gmail.com>
Cc: Adam Spiers <git@adamspiers.org>, Git mailing list <git@vger.kernel.org>
Subject: Re: git-log: documenting pathspec usage
Date: Mon, 16 Nov 2020 12:46:11 -0500	[thread overview]
Message-ID: <63667234-DCBD-4ED3-BF80-664CD5981874@gmail.com> (raw)
In-Reply-To: <878sb1fpep.fsf@evledraar.gmail.com>

Hi Adam, Hi Ævar,

> Le 16 nov. 2020 à 07:37, Ævar Arnfjörð Bjarmason <avarab@gmail.com> a écrit :
> 
> 
> On Mon, Nov 16 2020, Adam Spiers wrote:
> 
>> Hi all,
>> 
>> I just noticed that git-log.txt has: 
>> 
>>    SYNOPSIS
>>    --------
>>    [verse]
>>    'git log' [<options>] [<revision range>] [[--] <path>...]
>> 
>> and builtin/log.c has: 
>> 
>>    static const char * const builtin_log_usage[] = {
>>            N_("git log [<options>] [<revision-range>] [[--] <path>...]"),
>> 
>> IIUC, the references to <path> should actually be <pathspec> instead,
>> as seen with other pathspec-supporting commands such as git add/rm
>> whose man pages are extra helpful in explicitly calling out how
>> pathspecs can be used, e.g.:
>> 
>>    OPTIONS
>>    -------
>>    <pathspec>...::
>>            Files to add content from.  Fileglobs (e.g. `*.c`) can
>>            be given to add all matching files.  Also a
>>            leading directory name (e.g. `dir` to add `dir/file1`
>>            and `dir/file2`) can be given to update the index to
>>            match the current state of the directory as a whole (e.g.
>>            specifying `dir` will record not just a file `dir/file1`
>>            modified in the working tree, a file `dir/file2` added to
>>            the working tree, but also a file `dir/file3` removed from
>>            the working tree). Note that older versions of Git used
>>            to ignore removed files; use `--no-all` option if you want
>>            to add modified or new files but ignore removed ones.
>>    +
>>    For more details about the <pathspec> syntax, see the 'pathspec' entry
>>    in linkgit:gitglossary[7].
>> 
>> Would it be fair to say the git-log usage syntax and man page should
>> be updated to match?  If so perhaps I can volunteer for that.
> 
> It seems like a good idea to make these consistent, if you're feeling
> more ambitious than just git-log's manpage then:
> 
>    $ git grep '<pathspec>' -- Documentation/git-*.txt|wc -l
>    54
>    $ git grep '<path>' -- Documentation/git-*.txt|wc -l
>    161

And 'ls-files' uses <files>...

> Most/all of these should probably be changed to one or the other.

I completely agree. I think <pathspec> should be used for every command
that takes a pathspec.

In general, there can be discrepancies between the
short help of each command and the "Synopsis" section of the long help
(man page). I wonder what we could do to try to keep these more in sync.
In addFor example, some 'git blame' options appear only in the short help, 

Ideally, there would be a single source of truth for both of these, in my opinion,
but that would mean that the documentation build would somehow have to be taught
to read the source code and find the 'usage' function for each Git command and feed that
to the synopsis section (although the synopsis is usually more detailed than
the usage). One can always dream...

> I've also long wanted (but haven't come up with a patch for) that part
> of gitglossary to be ripped out into its own manual page,
> e.g. "gitpathspec(5)".

That is also on my personal todo list for Git. I think it's a great idea. This way
commands that take a pathspec could then link directly to this new guide.

Cheers,

Philippe.



  reply	other threads:[~2020-11-16 17:47 UTC|newest]

Thread overview: 4+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-11-16 12:22 Adam Spiers
2020-11-16 12:37 ` Ævar Arnfjörð Bjarmason
2020-11-16 17:46   ` Philippe Blain [this message]
2020-11-16 18:55   ` Junio C Hamano

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

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=63667234-DCBD-4ED3-BF80-664CD5981874@gmail.com \
    --to=levraiphilippeblain@gmail.com \
    --cc=avarab@gmail.com \
    --cc=git@adamspiers.org \
    --cc=git@vger.kernel.org \
    --subject='Re: git-log: documenting pathspec usage' \
    /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

Code repositories for project(s) associated with this inbox:

	https://80x24.org/mirrors/git.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).