docs: clarify git rm --cached function in gitignore note

From: Sohom <[email protected]>

Added text explaining that the git rm --cached command isn't analogous to the gitignore file and that the file will need to be added to gitignore to prevent later commits from adding the file back.

---
docs: Clarify git rm --cached function in gitignore note

Added text explaining that the git rm --cached command isn't analogous to the gitignore file and that the file will need to be added to gitignore to prevent later commits from adding the file back.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-862%2Fsohomdatta1%2Fgitignore-note-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-862/sohomdatta1/gitignore-note-v1
Pull-Request: https://github.com/git/git/pull/862

 Documentation/gitignore.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

index d47b1ae296..22d58df805 100644
@@ -147,7 +147,9 @@ The purpose of gitignore files is to ensure that certain files
 not tracked by Git remain untracked.
 
 To stop tracking a file that is currently tracked, use
-'git rm --cached'.
+'git rm --cached' to remove the file from the index. The filename
+can then be added to the `gitignore` file to stop the file from
+being reintroduced in later commits.
 
 EXAMPLES
 --------

base-commit: ab4691b67bc1a2cd8d9068fb03e3fbd6979247d6

gitgitgadget

Hey maintainers,

Friendly ping regarding this patch (I assume it slipped through the cracks).

It would be great if the change could be made to the git documentation, since it still is a common misconception amongst students that merely adding a file to .gitignore will lead to the file being automagically ignored by git when that is in fact not the case.

P.S: [email protected] and [email protected] are both me, that email was used by me previously when I was affiliated to my university.

Regards,
Sohom Datta.

Hi,

Yeah, looks like it slipped through the cracks. The documentation change looks reasonable to me, though given the time that has passed, the context region has changed so it no longer cleanly applies. Could you rebase it and resubmit?

Also, while rebasing, the "isn't analogous" part of the commit message feels like it misses the mark in the explanation, and the body of the commit message would be better worded in the imperative tense. Perhaps change the main paragraph to something like:

Explain to users that the step to untrack a file will not also keep it untracked in the future.

When you resubmit, go ahead and cc me.

From: Sohom <[email protected]>

Explain to users that the step to untrack a file will not also keep it untracked in the future.

---
docs: Clarify git rm --cached function in gitignore note

Added text explaining that the git rm --cached command isn't analogous to the gitignore file and that the file will need to be added to gitignore to prevent later commits from adding the file back.

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-862%2Fsohomdatta1%2Fgitignore-note-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-862/sohomdatta1/gitignore-note-v2
Pull-Request: https://github.com/git/git/pull/862

Range-diff vs v1:

1: 053e9f99c9e ! 1: c3257398c8f docs: clarify git rm --cached function in gitignore note
@@ Metadata
## Commit message ##
docs: clarify git rm --cached function in gitignore note

- Added text explaining that the git rm --cached command
- isn't analogous to the gitignore file and that the file
- will need to be added to gitignore to prevent later
- commits from adding the file back.
+ Explain to users that the step to untrack a file will not also keep it
+ untracked in the future.

@@ Documentation/gitignore.txt: The purpose of gitignore files is to ensure that ce
+can then be added to the gitignore file to stop the file from +being reintroduced in later commits.

- EXAMPLES
- --------
+ Git does not follow symbolic links when accessing a .gitignore file in
+ the working tree. This keeps behavior consistent when the file is

 Documentation/gitignore.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

index f2738b10db6..8b78e1b3e08 100644
@@ -146,7 +146,9 @@ The purpose of gitignore files is to ensure that certain files
 not tracked by Git remain untracked.
 
 To stop tracking a file that is currently tracked, use
-'git rm --cached'.
+'git rm --cached' to remove the file from the index. The filename
+can then be added to the `gitignore` file to stop the file from
+being reintroduced in later commits.
 
 Git does not follow symbolic links when accessing a `.gitignore` file in
 the working tree. This keeps behavior consistent when the file is

base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8

gitgitgadget

Please make sure this line matches what you sign-off the patch as, i.e. the above line should read more like

From: Sohom Datta <[email protected]>

"also keep it untracked" -> "prevent them from getting added"?

After all, it is not "git" that makes the path tracked. It is the user who says "git add" that file that is not supposed to be tracked.

From: Sohom Datta <[email protected]>

Explain to users that the step to untrack a file will not also prevent them from getting added in the future.

---
docs: Clarify git rm --cached function in gitignore note

I've fixed the Sign-Off v/s commit author issue and incorporated the changes suggested :)

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-git-862%2Fsohomdatta1%2Fgitignore-note-v3
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-git-862/sohomdatta1/gitignore-note-v3
Pull-Request: https://github.com/git/git/pull/862

Range-diff vs v2:

1: c3257398c8f ! 1: ae09ff2e70c docs: clarify git rm --cached function in gitignore note
@@
## Metadata ##
-Author: Sohom <[email protected]>
+Author: Sohom Datta <[email protected]>

## Commit message ##
docs: clarify git rm --cached function in gitignore note

- Explain to users that the step to untrack a file will not also keep it
- untracked in the future.
+ Explain to users that the step to untrack a file will not also prevent them
+ from getting added in the future.

@@ Documentation/gitignore.txt: The purpose of gitignore files is to ensure that ce
To stop tracking a file that is currently tracked, use
-'git rm --cached'.
+'git rm --cached' to remove the file from the index. The filename
-+can then be added to the gitignore file to stop the file from ++can then be added to the .gitignore file to stop the file from
+being reintroduced in later commits.

Git does not follow symbolic links when accessing a .gitignore file in

 Documentation/gitignore.txt | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

index f2738b10db6..4c17f2356c4 100644
@@ -146,7 +146,9 @@ The purpose of gitignore files is to ensure that certain files
 not tracked by Git remain untracked.
 
 To stop tracking a file that is currently tracked, use
-'git rm --cached'.
+'git rm --cached' to remove the file from the index. The filename
+can then be added to the `.gitignore` file to stop the file from
+being reintroduced in later commits.
 
 Git does not follow symbolic links when accessing a `.gitignore` file in
 the working tree. This keeps behavior consistent when the file is

base-commit: 69c786637d7a7fe3b2b8f7d989af095f5f49c3a8

gitgitgadget

v3 looks good to me: