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

From: Jonathan Nieder <jrnieder@gmail.com>
Date: Nov 10, 2010, 18:55 UTC
Message-ID: <20101110185555.GA12365@burratino>
In-Reply-To: <1289387440-8509-1-git-send-email-sitaram@atc.tcs.com>

Sitaram Chamarty wrote:

Show 9 quoted lines

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

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