Re: [PATCH] gitignore(5): explain how to stop tracking a file

Sitaram Chamarty wrote:

Ack.  But I fear this makes the gitignore page feel even more top-heavy
than it already is.

The current structure is:

	SYNOPSIS
	[list of excludes files]

	DESCRIPTION
	One-sentence description.  Long comment about some totally
	different command.

	Description of structure.  Long comment about precedence rules:

	. some rules
	...

	Paragraph about which excludes file works for which use case.

	Paragraph about which commands pay attention to excludes files.

	Patterns have the following format:

	. some rules
	...

	An example:

	 transcript

	Another example:

	 transcript

	Quick analysis.

	DOCUMENTATION
	Various people's names.

	GIT
	Part of the git(1) suite.

It's a wonder people can find anything there. :)  So how about this?

Patch 1 splits the description into three sections.  Yes, having the
PATTERN FORMAT section is not part of the conventional list in
man-pages(7), but I think it's easier to find the interesting part
this way.

Patch 2 puts the comments about related commands in a separate NOTES
section.

This way, one could expand on the "stop tracking file" procedure
without interrupting the flow of the basic description of what
excludes files do, by adding to the NOTES or EXAMPLES section.

Thoughts?

Jonathan Nieder (2):
  Documentation: split gitignore page into sections
  Documentation: point to related commands from gitignore

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

-- 
1.7.2.3.557.gab647.dirty

A learner-by-example might want to look at the examples section first.
Help her out by supplying some section headings: PATTERN FORMAT for
the format of lines in an excludes file and EXAMPLES for the two
examples.

Signed-off-by: Jonathan Nieder <redacted>
---
 Documentation/gitignore.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 7dc2e8b..254bc1a 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt

@@ -62,7 +62,8 @@ files specified by command-line options.  Higher-level git
 tools, such as 'git status' and 'git add',
 use patterns from the sources specified above.
 
-Patterns have the following format:
+PATTERN FORMAT
+--------------
 
  - A blank line matches no files, so it can serve as a separator
    for readability.

@@ -98,7 +99,8 @@ Patterns have the following format:
    For example, "/{asterisk}.c" matches "cat-file.c" but not
    "mozilla-sha1/sha1.c".
 
-An example:
+EXAMPLES
+--------
 
 --------------------------------------------------------------
     $ git status

-- 
1.7.2.3.557.gab647.dirty

A frequently asked question on #git is how to stop tracking a file
that is mistakenly tracked by git.  A frequently attempted strategy is
to add such files to .gitignore.

Thus one might imagine that the gitignore documentation could be a
good entry point for 'git rm' documentation.  Add some
cross-references in this vein.

While at it, move a reference to update-index --assume-unchanged from
the DESCRIPTION to lower down on the page.  This way, the methodical
reader can benefit from first learning what excludes files do, then
how they relate to other git facilities.

Based-on-patch-by: Sitaram Chamarty [off-list ref]
Signed-off-by: Jonathan Nieder <redacted>
---
 This NOTES section is a bit of a placeholder.  I think it is an
 improvement already, but if someone wants to flesh it out I wouldn't
 complain.

 Hope that helps.

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

diff --git a/Documentation/gitignore.txt b/Documentation/gitignore.txt
index 254bc1a..8416f34 100644
--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt

@@ -14,11 +14,8 @@ DESCRIPTION
 
 A `gitignore` file specifies intentionally untracked files that
 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.
+Files already tracked by git are not affected; see the NOTES
+below for details.
 
 Each line in a `gitignore` file specifies a pattern.
 When deciding whether to ignore a path, git normally checks

@@ -99,6 +96,18 @@ PATTERN FORMAT
    For example, "/{asterisk}.c" matches "cat-file.c" but not
    "mozilla-sha1/sha1.c".
 
+NOTES
+-----
+
+The purpose of gitignore files is to ensure that certain files
+not tracked by git remain untracked.
+
+To ignore uncommitted changes in a file that is already tracked,
+use 'git update-index {litdd}assume-unchanged'.
+
+To stop tracking a file that is currently tracked, use
+'git rm --cached'.
+
 EXAMPLES
 --------
 

@@ -142,6 +151,11 @@ Another example:
 The second .gitignore prevents git from ignoring
 `arch/foo/kernel/vmlinux.lds.S`.
 
+SEE ALSO
+--------
+linkgit:git-rm[1], linkgit:git-update-index[1],
+linkgit:gitrepository-layout[5]
+
 Documentation
 -------------
 Documentation by David Greaves, Junio C Hamano, Josh Triplett,

-- 
1.7.2.3.557.gab647.dirty

On Thu, Nov 11, 2010 at 12:25 AM, Jonathan Nieder [off-list ref] wrote:

Sitaram Chamarty wrote:

quoted

--- a/Documentation/gitignore.txt
+++ b/Documentation/gitignore.txt

@@ -18,7 +18,8 @@ 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.
+documentation.  To stop tracking a file that is currently tracked,
+use 'git rm --cached'.

Ack.  But I fear this makes the gitignore page feel even more top-heavy
than it already is.

Oh... I hadn't thought of that.  I was looking at "what's the minimum
change needed to at least mention 'git rm --cached' somewhere".
You're right though, and I think your approach is good.

The current structure is:

[snip]

It's a wonder people can find anything there. :)  So how about this?

Patch 1 splits the description into three sections.  Yes, having the
PATTERN FORMAT section is not part of the conventional list in
man-pages(7), but I think it's easier to find the interesting part
this way.

Patch 2 puts the comments about related commands in a separate NOTES
section.

This way, one could expand on the "stop tracking file" procedure
without interrupting the flow of the basic description of what
excludes files do, by adding to the NOTES or EXAMPLES section.

++ from me on this approach.

regards

sitaram