thodg/libgit2

2018-07-13T21:29:01

ignore: improve `git_ignore_path_is_ignored` description Git analogy In attempt to provide adequate Git command analogy in regards to ignored files handling, `git_ignore_path_is_ignored` description mentions doing `git add .` on directory containing the file, and whether the file in question would be added or not - but behavior of the two matches for untracked files only, making the comparison misleading in general sense. For tracked files, Git doesn't subject them to ignore rules, so even if a rule applies, `git add .` would actually add the tracked file changes to index, while `git_ignore_path_is_ignored` would still consider the file being ignored (as it doesn't check the index, as documented). Let's provide `git check-ignore --no-index` as analogous Git command example instead, being more aligned with what `git_ignore_path_is_ignored` is about, no matter if the file in question is already tracked or not. See issue #4720 (git_ignore_path_is_ignored documentation misleading?, 2018-07-10)[1] for additional information. [1] https://github.com/libgit2/libgit2/issues/4720

diff --git a/include/git2/ignore.h b/include/git2/ignore.h
index d0c1877..f5143f3 100644
--- a/include/git2/ignore.h
+++ b/include/git2/ignore.h
@@ -59,8 +59,8 @@ GIT_EXTERN(int) git_ignore_clear_internal_rules(
  * given file.  This indicates if the file would be ignored regardless of
  * whether the file is already in the index or committed to the repository.
  *
- * One way to think of this is if you were to do "git add ." on the
- * directory containing the file, would it be added or not?
+ * One way to think of this is if you were to do "git check-ignore --no-index"
+ * on the given file, would it be shown or not?
  *
  * @param ignored boolean returning 0 if the file is not ignored, 1 if it is
  * @param repo a repository object