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

From: Duy Nguyen <pclouds@gmail.com>
Date: Jun 30, 2016, 15:14 UTC
Message-ID: <CACsJy8AES0iu341DU6FDYZq6fmssbD3QSZaiwi9BntTnMQS5Gw@mail.gmail.com>
In-Reply-To: <5774E992.7070905@gmail.com>

Hi Jakub,

Where have you been all these years? :D

On Thu, Jun 30, 2016 at 11:42 AM, Jakub Narębski <jnareb@gmail.com> wrote:

Show 10 quoted lines

>>>>> 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,

git-pathspec(7) is a great idea. It bugs me that all the pathspec details are hidden in that glossary file (though I didn't know it was also available via "git help glossary", which probably just reinforces its invisibility). The closet place I could think of was git(1) but that page is already very long.

> 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.);

You mean the list of commands in this man page? OK. Another thing we could do is the reverse direction, add gitpathspec(7) as a reference to all commands that may need it.

> the pathspec
> in strict sense is about the input. Well, we could have 'manpage
> alias' of gitpaths to gitpathspec, or vice versa.

Show 5 quoted lines

>  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.

I have that problem sometimes and I don't think I can call myself a noob anymore. I usually need to do some grepping. So yeah "git apropos" would be great.

-- 
Duy