Documentation: How to ignore local changes in tracked files

This patch explains more carefully that `.gitignore` concerns only untracked files and refers the reader to git update-index --assume-unchanged in the need of ignoring uncommitted changes in already tracked files. The description of this option is lifted to a more "porcelainish" level and explains the caveats of this usecase. Whether feasible or not, I believe adding this functionality to the porcelain is out of the scope of this patch. (And I personally think that referring to the plumbing in the case of such a special usage is fine.) This is currently probably one of the top FAQs at #git and the --assume-unchanged switch is not widely known; gitignore(5) is the first place where people are likely to look for it. Signed-off-by: Petr Baudis <pasky@suse.cz> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Petr Baudis committed Jul 18, 2008 at 16:11 UTC 6259ac6628477aa5ebde9bd9e8daaeecca2a74ae

2 files changed +18 -3

Documentation/git-update-index.txt

+10

@@ -88,6 +88,16 @@ OPTIONS

88 sometimes helpful when working with a big project on a

89 filesystem that has very slow lstat(2) system call

90 (e.g. cifs).

91 ++

92 +This option can be also used as a coarse file-level mechanism

93 +to ignore uncommitted changes in tracked files (akin to what

94 +`.gitignore` does for untracked files).

95 +You should remember that an explicit 'git add' operation will

96 +still cause the file to be refreshed from the working tree.

97 +Git will fail (gracefully) in case it needs to modify this file

98 +in the index e.g. when merging in a commit;

99 +thus, in case the assumed-untracked file is changed upstream,

100 +you will need to handle the situation manually.

101

102 -g::

103 --again::

Documentation/gitignore.txt

+8 -3

@@ -13,9 +13,14 @@ DESCRIPTION

13 -----------

15 A `gitignore` file specifies intentionally untracked files that

16 -git should ignore. Each line in a `gitignore` file specifies a

17 -pattern.

18 -

16 +git should ignore.

17 +Note that all the `gitignore` files really concern only files

18 +that are not already tracked by git;

19 +in order to ignore uncommitted changes in already tracked files,

20 +please refer to the 'git update-index --assume-unchanged'

21 +documentation.

22 +

23 +Each line in a `gitignore` file specifies a pattern.

24 When deciding whether to ignore a path, git normally checks

25 `gitignore` patterns from multiple sources, with the following

26 order of precedence, from highest to lowest (within one level of