patchRe: [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(-)

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 <jrnieder@gmail.com>
---
 Documentation/gitignore.txt |    6 ++++--
 1 files changed, 4 insertions(+), 2 deletions(-)

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 <sitaram@atc.tcs.com>
Signed-off-by: Jonathan Nieder <jrnieder@gmail.com>
---
 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(-)

Jonathan Nieder <jrnieder@gmail.com> writes:

Looks sensible.

I am not very happy with the wording "to do X, use Y" above, though. For example, "rm --cached" is a good starting point, but that needs to be followed by a commit some time in the future to take permanent effect. The realization that "rm --cached" is a good starting point would come only with an understanding of what "rm --cached" does (i.e. it removes the path from the index, preparing for its removal from the future history).

"to do X, see Y" might be a good compromise, because what I am suggesting by the above is that ideally to say "to do X means doing Z so using Y is a good way to achieve it", but "... means doing Z" part is explained in the manual page of Y.

In any case, will queue.  Thanks.

On Thu, Nov 11, 2010 at 12:25 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

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.

[snip]

++ from me on this approach.

regards

sitaram