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

["Jakub Narębski" <jnareb@gmail.com>]

W dniu 2016-06-29 o 23:28, Junio C Hamano pisze:
> 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