Re: [RFD] Place to document magic pathspecs like ":/" and pathspec handling

From: Jakub Narębski <jnareb@gmail.com>
Date: Jun 30, 2016, 09:42 UTC
Message-ID: <5774E992.7070905@gmail.com>
In-Reply-To: <xmqqy45n1y8a.fsf@gitster.mtv.corp.google.com>

W dniu 2016-06-29 o 23:28, Junio C Hamano pisze:

Show 14 quoted lines

> Jakub Narębski <jnareb@gmail.com> writes:
> 
>> But I think it is not the best place to keep this documentation.
> 
> All true.  In case it was not obvious, I didn't mean to say "Here
> you find the information, shut up."  It was "here is a pointer if
> you didn't find it, so that you can use it as a starting point to
> make a better documentation."
> 
> An analogous entity in the world model of Git that appears
> everywhere and is not limited to a single command is the revision
> set calculus.  Where do we describe it and how do we make it
> discoverable?  Can the new way to describe pathspec and pathspec
> magic mimic the way it is done for the revisions?

Is that a trick question? :-P

The revision set calculus is described as a standalone documentation in the gitrevisions(7) manpage (titled "specifying revisions and [revision] ranges for Git"... well, the "[revision]" isn't there). This documentation is also accessible via `git help revisions`, which is cool. It is referenced in the "Symbolic Identifiers" section of the git(1) manual page.

Long time ago the description of revision set calculus was hidden in the manpage for the plumbing command git-rev-parse, and is still included in it (the common part is, via "include::revisions.txt[]").

As I wrote:

>>>> Nowadays we have gitcli(7) manual page, but perhaps
>>>> it would be better to create a separate manpage for issues related
>>>> to pathspec handling (of which ":/" is only one part)... but then
>>>> what should it be named?

So we could describe how Git handles pathspecs and pathspec magic in the new manual page named gitpathspec(7), or gitpaths(7). The former has the advantage of the name being identical to the entry in gitglossary(7). The latter has the probable advantage of being easier for the Git novice to find, and that it could be used to gather various ways to generate list of files in Git (files in the working area, files in the staging area aka the index, files in the revision / tree object, changed files, etc.); the pathspec in strict sense is about the input. Well, we could have 'manpage alias' of gitpaths to gitpathspec, or vice versa.

 Sidenote: I wonder if people (especially novices) have problem
 finding relevant documentation, and if adding something like 
 "git apropos <topic>" command ("apropos", or "man -k"), or
 add the '--apropos' option to "git help" would be useful...
 and if it would be easy to create.

The description from gitglossary would be a good start, as would parts of gitcli and relevant RelNotes. It would need to be linked from git(1) manpage, and probably also from gitcli.

Now only to start it...

-- 
Jakub Narębski