Documentation/gitignore.txt: Clarify gitignore vs tracked files
PATCH 1/1 Documentation/gitignore.txt: Clarify gitignore vs tracked files
Explain more carefully that .gitignore concerns only untracked files and there is no way to make git ignore local changes in already tracked files.
This is currently probably one of the top FAQs at #git and the documentation could be more explicit about this.
---
Documentation/gitignore.txt | 7 +++++-- 1 files changed, 5 insertions(+), 2 deletions(-)
Documentation/gitignore.txt +5 -2
@@ -13,9 +13,12 @@ DESCRIPTION ----------- A `gitignore` file specifies intentionally untracked files that -git should ignore. Each line in a `gitignore` file specifies a -pattern. +git should ignore. +Note that all the `gitignore` files really concern only files +that are not already tracked by git; there is no direct mechanism +to make git ignore your local modifications in already tracked files. +Each line in a `gitignore` file specifies a pattern. When deciding whether to ignore a path, git normally checks `gitignore` patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of
Documentation/gitignore.txt DESCRIPTION · line 19
Quoted 6 lines · Petr Baudis
Documentation/gitignore.txt +4
-2-git should ignore. Each line in a `gitignore` file specifies a -pattern. +git should ignore. +Note that all the `gitignore` files really concern only files +that are not already tracked by git; there is no direct mechanism +to make git ignore your local modifications in already tracked files.
Thanks.
I'd suggest dropping everything after ';'.
- If you want to keep local changes without ever checking in, you can do so by making partial commits.
- You could mark these paths "assume unchanged".
Hi,
Quoted 1 line · Junio C Hamano
I'd suggest dropping everything after ';'.
I think the part after ';' is the main benefit of this patch,
actually. Without suggesting an alternative, the users are left puzzled "so how do I do that?"
Quoted 2 lines
- If you want to keep local changes without ever checking in, you can do so by making partial commits.
Yes, that's a rather obvious solution but the user probably wants
something nicer than that if he starts looking already.
Quoted 1 line
- You could mark these paths "assume unchanged".
I really think this is worth mentioning in the gitignore manpage;
it is not _directly_ on-topic, but there is no other obvious place where to teach users about it and all the interested people will check the gitignore manpage first. Perhaps a small section at the end might be acceptable? ;-)
Signature · 4 lines
Petr "Pasky" Baudis GNU, n. An animal of South Africa, which in its domesticated state resembles a horse, a buffalo and a stag. In its wild condition it is something like a thunderbolt, an earthquake and a cyclone. -- A. Pierce
PATCH 1/1 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.
---
Documentation/git-update-index.txt | 10 ++++++++++ Documentation/gitignore.txt | 11 ++++++++--- 2 files changed, 18 insertions(+), 3 deletions(-)
Documentation/git-update-index.txt +10 -0
@@ -88,6 +88,16 @@ OPTIONS sometimes helpful when working with a big project on a filesystem that has very slow lstat(2) system call (e.g. cifs). ++ +This option can be also used as a coarse file-level mechanism +to ignore uncommitted changes in tracked files (akin to what +`.gitignore` does for untracked files). +You should remember that an explicit 'git add' operation will +still cause the file to be refreshed from the working tree. +Git will fail (gracefully) in case it needs to modify this file +in the index e.g. when merging in a commit; +thus, in case the assumed-untracked file is changed upstream, +you will need to handle the situation manually. -g:: --again::
Documentation/gitignore.txt +8 -3
@@ -13,9 +13,14 @@ DESCRIPTION ----------- A `gitignore` file specifies intentionally untracked files that -git should ignore. Each line in a `gitignore` file specifies a -pattern. - +git should ignore. +Note that all the `gitignore` files really concern only files +that are not already tracked by git; +in order to ignore uncommitted changes in already tracked files, +please refer to the 'git update-index --assume-unchanged' +documentation. + +Each line in a `gitignore` file specifies a pattern. When deciding whether to ignore a path, git normally checks `gitignore` patterns from multiple sources, with the following order of precedence, from highest to lowest (within one level of