git@vger.kernel.org list mirror (unofficial, one of many)
 help / color / mirror / code / Atom feed
* git-log: documenting pathspec usage
@ 2020-11-16 12:22 Adam Spiers
  2020-11-16 12:37 ` Ævar Arnfjörð Bjarmason
  0 siblings, 1 reply; 4+ messages in thread
From: Adam Spiers @ 2020-11-16 12:22 UTC (permalink / raw)
  To: git mailing list

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.

Regards,
Adam

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: git-log: documenting pathspec usage
  2020-11-16 12:22 git-log: documenting pathspec usage Adam Spiers
@ 2020-11-16 12:37 ` Ævar Arnfjörð Bjarmason
  2020-11-16 17:46   ` Philippe Blain
  2020-11-16 18:55   ` Junio C Hamano
  0 siblings, 2 replies; 4+ messages in thread
From: Ævar Arnfjörð Bjarmason @ 2020-11-16 12:37 UTC (permalink / raw)
  To: Adam Spiers; +Cc: git mailing list


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

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

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)". And if possible for "PATTERN FORMAT" in
"gitignore" to be unified with that/other docs that describe how our
wildmatch.c works.

There's also the "Conditional includes" section in git-config(1) that
repeats some of that, and probably other stuff I'm forgetting
#leftoverbits.

^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: git-log: documenting pathspec usage
  2020-11-16 12:37 ` Ævar Arnfjörð Bjarmason
@ 2020-11-16 17:46   ` Philippe Blain
  2020-11-16 18:55   ` Junio C Hamano
  1 sibling, 0 replies; 4+ messages in thread
From: Philippe Blain @ 2020-11-16 17:46 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason; +Cc: Adam Spiers, Git mailing list

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.



^ permalink raw reply	[flat|nested] 4+ messages in thread

* Re: git-log: documenting pathspec usage
  2020-11-16 12:37 ` Ævar Arnfjörð Bjarmason
  2020-11-16 17:46   ` Philippe Blain
@ 2020-11-16 18:55   ` Junio C Hamano
  1 sibling, 0 replies; 4+ messages in thread
From: Junio C Hamano @ 2020-11-16 18:55 UTC (permalink / raw)
  To: Ævar Arnfjörð Bjarmason; +Cc: Adam Spiers, git mailing list

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> 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
>
> Most/all of these should probably be changed to one or the other.

There is another thing we want to normalize.

Originally <pathspec> was invented to be a collective noun (i.e. a
set of one or more wildmatch patterns that specify paths that match
any of these patterns is called a pathspec).  These days, however,
we more often refer to each individual pattern as <pathspec> than
using the word in its original way.  We can look for '<pathspec>...'
in the documentation to find these more modern usage.

This latter form would match readers' expectation better, but there
still are a few places (e.g. "stash forget <pathspec>") that use the
word as a collection of pattterns.  While these places may be using
the word "correctly", in the modern world, they give an incorrect
impression that the command somehow is special and can take a
pathspec with only a single pattern, when they can take one or more
patterns.

We should make sure we use "<pathspec>..."  uniformly in the
documentation in these places.

Thanks.


^ permalink raw reply	[flat|nested] 4+ messages in thread

end of thread, other threads:[~2020-11-16 18:57 UTC | newest]

Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-11-16 12:22 git-log: documenting pathspec usage Adam Spiers
2020-11-16 12:37 ` Ævar Arnfjörð Bjarmason
2020-11-16 17:46   ` Philippe Blain
2020-11-16 18:55   ` Junio C Hamano

git@vger.kernel.org list mirror (unofficial, one of many)

This inbox may be cloned and mirrored by anyone:

	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

	# If you have public-inbox 1.1+ installed, you may
	# initialize and index your mirror using the following commands:
	public-inbox-init -V1 git git/ https://public-inbox.org/git \
		git@vger.kernel.org
	public-inbox-index git

Example config snippet for mirrors.
Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://7fh6tueqddpjyxjmgtdiueylzoqt6pt7hec3pukyptlmohoowvhde4yd.onion/inbox.comp.version-control.git
	nntp://ie5yzdi7fg72h7s4sdcztq5evakq23rdt33mfyfcddc5u3ndnw24ogqd.onion/inbox.comp.version-control.git
	nntp://4uok3hntl7oi7b4uf4rtfwefqeexfzil2w6kgk2jn5z2f764irre7byd.onion/inbox.comp.version-control.git
	nntp://news.gmane.io/gmane.comp.version-control.git
 note: .onion URLs require Tor: https://www.torproject.org/

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

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

AGPL code for this site: git clone https://public-inbox.org/public-inbox.git