Explain which gitignore rule is ignoring my file

Is there any way to see why some file is getting ignored by git (i.e. which rule in a .gitignore file is causing the file to be ignored)?

Imagine I have this (or a much more complex scenario, with hundreds of folders and tens of .gitignore files:

/
-.gitignore
-folder/
    -.gitignore
    -subfolder/
              -.gitignore
              -file.txt

If I run git add folder/subfolder/file.txt git may complain of it being ignored:

The following paths are ignored by one of your .gitignore files:
folder/subfolder/file.txt
Use -f if you really want to add them.

Is there any way to know which of all the possible .gitignore have a rule to ignore this file, and also show the rule? Like:

The following paths are ignored by your folder/.gitignore file (line 12: *.txt)
folder/subfolder/file.txt
Use -f if you really want to add them.

Or just:

$ git why-is-ignored folder/subfolder/file.txt
folder/.gitignore:12:*.txt

Solution 1:

git check-ignore -v filename

See the man page for more details.

Original answer follows:

git does not currently provide anything like this. But after seeing your question I did some googling and found that back in 2009 this feature was requested and partially implemented. After reading the thread, I realised it would not be too much work to do it properly, so I have started work on a patch and hope to have it finished in the next day or two. I will update this answer when it is ready.

UPDATE: Wow, that was a lot harder than I expected. The innards of git's exclude handling are quite cryptic. Anyway, here's an almost finished series of commits which apply to today's upstream master branch. The test suite is 99% complete, but I haven't finished handling of the --stdin option yet. Hopefully I'll manage that this weekend, and then submit my patches to the git mailing list.

In the meantime, I'd definitely welcome testing from anyone who's able to do so - just clone from my git fork, check out the check-ignore branch, and compile it as normal.

UPDATE 2: It's done! Latest version is on github as per above, and I have submitted the patch series to the git mailing list for peer review. Let's see what they think ...

UPDATE 3: After several more months of hacking / patch reviews / discussions / waiting, I'm delighted to be able to say that this feature has now reached git's master branch, and will be available in the next release (1.8.2, expected 8th March 2013). Here's the check-ignore manual page. Phew, that was way more work than I expected!

UPDATE 4: If you're interested in the full story about how this answer evolved and the feature came to be implemented, check out episode #32 of the GitMinutes podcast.

Solution 2:

Update git 2.8 (March 2016):

GIT_TRACE_EXCLUDE=1 git status

See "A way to validate .gitignore file"

That is complementary to the git check-ignore -v described below.

Original answer: Sept 2013 (git 1.8.2, then 1.8.5+):

git check-ignore improves again in git 1.8.5/1.9 (Q4 2013):

"git check-ignore" follows the same rule as "git add" and "git status" in that the ignore/exclude mechanism does not take effect on paths that are already tracked.
With "--no-index" option, it can be used to diagnose which paths that should have been ignored have been mistakenly added to the index.

See commit 8231fa6 from https://github.com/flashydave:

check-ignore currently shows how .gitignore rules would treat untracked paths. Tracked paths do not generate useful output.
This prevents debugging of why a path became tracked unexpectedly unless that path is first removed from the index with git rm --cached <path>.

The option --no-index tells the command to bypass the check for the path being in the index and hence allows tracked paths to be checked too.

Whilst this behaviour deviates from the characteristics of git add and git status its use case is unlikely to cause any user confusion.

Test scripts are augmented to check this option against the standard ignores to ensure correct behaviour.

--no-index::

Don't look in the index when undertaking the checks.
This can be used:

• to debug why a path became tracked by e.g. git add . and was not ignored by the rules as expected by the user or
• when developing patterns including negation to match a path previously added with git add -f.

Solution 3:

It may not be .gitignore -- 3 possible ignore reasons

A file may be ignored for the following reasons:

1. .gitignore
2. git update-index --skip-worktree
3. git update-index --assume-unchanged

Additionally, a file may be UNignored by if it is in .gitignore AND already staged in the index/cache.

To check for the enumerated cases above:

1. For the two cases of .gitignore excludes, compare the output of:

   • git check-ignore --verbose --non-matching --no-index file1 file2 file3
   • git check-ignore --verbose --non-matching file1 file2 file3

2. git ls-files file1 file2 file3 | grep -E '^S'

3. git ls-files file1 file2 file3 | grep -E '^[[:lower:]]'

That's too hard, just give me an alias!

The following aliases will cover all the cases listed above:

ignore = !"bash -c 'diff --unified=999999999 --color=always <(echo a; git check-ignore --verbose --non-matching --no-index . \"$@\") <(echo b; git check-ignore --verbose --non-matching . \"$@\")' - \"$@\" | tail -n+7; git hidden \"$@\" # Show ignore status of arguments. Files included by index are tagged with prepended '+'."
hidden = !"git ls-files -v -- \"$@\"| grep -E '^(S|[[:lower:]])' # S means update-index --skip-worktree, and lower first letter means --assume-unchanged."

The comment and final " are part of the line to be copied to your .gitconfig.

Usage:

git ignore file1 file2 file3

Solution 4:

I can't find anything in the man page but here's a quick and dirty script that will check your file in each parent directory to see if it can be git-add'ed. Run it in the directory containing the problem file as:

test-add.sh STOP_DIR FILENAME

where STOP_DIR is the top level directory of the Git project and FILENAME is the problem file name (without a path). It creates an empty file of the same name at each level of the hierarchy (if it doesn't exist) and tries a git add -n to see if it can be added (it cleans up after itself). It outputs something like:

FAILED:    /dir/1/2/3
SUCCEEDED: /dir/1/2

The script:

#!/usr/bin/env bash
TOP=$1
FILE=$2
DIR=`pwd`
while : ; do
  TMPFILE=1
  F=$DIR/$FILE
  if [ ! -f $F ]; then
    touch $F
    TMPFILE=0
  fi
  git add -n $F >/dev/null 2>&1
  if [ $? = 0 ]; then
    echo "SUCCEEDED: $DIR"
  else
    echo "FAILED:    $DIR"
  fi
  if [ $TMPFILE = 0 ]; then
    rm $F
  fi
  DIR=${DIR%/*}
  if [ "$DIR" \< "$TOP" ]; then
    break
  fi
done