[PATCH] Documentation/gitignore.txt: Clarify gitignore vs tracked files

[PATCH] Documentation/gitignore.txt: Clarify gitignore vs tracked files

[Petr Baudis]

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.

Signed-off-by: Petr Baudis <pasky@suse.cz>
---

 Documentation/gitignore.txt |    7 +++++--
 1 files changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index fc0efd8..ac3c776 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -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

Re: [PATCH] Documentation/gitignore.txt: Clarify gitignore vs tracked files

[Junio C Hamano]

Petr Baudis <pasky@suse.cz> writes:

> -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".

Re: [PATCH] Documentation/gitignore.txt: Clarify gitignore vs tracked files

[Petr Baudis]

  Hi,

On Thu, Jul 17, 2008 at 11:16:59AM -0700, Junio C Hamano wrote:
> 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?"

>  - 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.

>  - 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? ;-)

-- 
				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] Documentation: How to ignore local changes in tracked files

[Petr Baudis]

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>
---

 Documentation/git-update-index.txt |   10 ++++++++++
 Documentation/gitignore.txt        |   11 ++++++++---
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/Documentation/git-update-index.txt b/Documentation/git-update-index.txt
index a91fd21..6b930bc 100644
--- a/Documentation/git-update-index.txt
+++ b/Documentation/git-update-index.txt
@@ -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::
diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index fc0efd8..59321a2 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt
@@ -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