Re: which files are "known to git"?

[Elijah Newren <newren@gmail.com>]

Hi Robert,

On Mon, May 21, 2018 at 4:18 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
>
>   updating my git courseware and, since some man pages refer to files
> "known to git", i just want to make sure i understand precisely which
> files those are. AIUI, they would include:
>
>   * tracked files
>   * ignored files
>   * new files which have been staged but not yet committed
>
> is that it? are there others?

Doesn't the first category of yours include the third?  I always read
'tracked' as 'in the index'.

I had always assumed prior to your email that 'known to Git' meant
'tracked' or 'recorded in the index'.  However, a quick `git grep -i
known.to.git` shows that we're actually not consistent by what we mean
with this phrase.  A little test setup:

  $ echo ignoreme >>.gitignore
  $ git add .gitignore
  $ git commit -m ignoreme
  $ touch ignoreme
  $ git ls-files -o
  ignoreme
  $ git ls-files -o --exclude-standard
  $

From Documentation/git-clean.txt:

    Normally, only files unknown to Git are removed, but if the `-x`
    option is specified, ignored files are also removed.

  This implies that ignored files are not 'unknown to Git', or fixing the
  double negative, that ignored files are 'known to Git':
  $ git clean -n
  $ git clean -nx
  Would remove ignoreme
  $

From Documentation/git-commit.txt:

    3. by listing files as arguments to the 'commit' command
       (without --interactive or --patch switch), in which
       case the commit will ignore changes staged in the index, and instead
       record the current content of the listed files (which must already
       be known to Git);

  This implies that only recorded-in-the-index files are known to Git:
  $ git commit -m testing ignoreme
  error: pathspec 'ignoreme' did not match any file(s) known to git.
  $

From Documentation/git-rm.txt:

    The <file> list given to the command can be exact pathnames,
    file glob patterns, or leading directory names.  The command
    removes only the paths that are known to Git.  Giving the name of
    a file that you have not told Git about does not remove that file.

  This also implies that only recorded-in-the-index files are known to Git:
  $ git rm ignoreme
  fatal: pathspec 'ignoreme' did not match any files
  $


I can't see any evidence of usage that suggests any more categories
than tracked and ignored, but whether ignored files are included in
the set of 'files known to Git' appears to depend on which man page
you are reading...which is rather unfortunate.

Robert, since you're working on documentation of sorts anyway, would
you like to propose some patches to fix things here?  I'm not entirely
sure what to suggest, and we might need a random suggestion to get the
discussion started before we figure out what we want here, but it'd be
nice to fix this inconsistency.


Elijah