Re: [PATCH v2 1/1] gitfaq: append the 'Common Issues' section

Shourya Shukla <shouryashukla.oo@gmail.com> writes:

(again, I'll wrap overly long lines, as they were unreviewable otherwise)

At least "they area" -> "they are" is needed, but it is unclear where these two sentences one to go.

"to ignore files from getting tracked in the working tree" is why you may want to use the '.gitignore' file. That is OK. But the connection to the next sentence, especially the subject "This ignores", is hard to grok. I am guessing that you want to tell the users something like

	Paths that match patterns listed in the `.gitignore` are
	not meant to be tracked.

	The act of adding a pattern in `.gitignore` that matches a
	set of paths that are not tracked is a declaration that you
	do not intend to track these paths and a request by you to
	Git to help you achieve that goal.

but you are trying to state it in a more approachable manner. But I sense that you ended up being unclear.

This part is very much in line with the "you are declaring and requesting". The user does not want to track these paths, and these commands are helping the user to achieve that wish.

However, "`git add` does not list ..." is questionable. by definition, Git does not care about contents of any untracked paths, so there is no way for us to say `modified` about them.

The primary utility of `git add` is to add a path, which used to be untracked, to the set of the paths that are tracked. So perhaps

	To help you keep the paths untracked, `git add` does not add
	the paths that are not tracked and ignored without the
	`--force` option, and `git status` does not list them as
	untracked (i.e. possible candidate that you might want to
	add but forgot).

I am not sure wat you mean by the first sentence (even after removing 'the' from "in the it."). It does not matter if you wrote the pattern '*.o' in the .gitignore file one year ago, or 7 seconds ago. As long as hello.o in the working tree is not tracked, it is ignored. Perhaps

	The `.gitignore` mechanism applies only to the files that
	are not already tracked.  A path that is already tracked
	will stay to be tracked even if you add a pattern that
	happens to match it to .gitignore file.

I'd omit "To amend this mistake, i.e.," from the above, if I were writing this. Also, I see no value in saying "completely" here. It is not like there are ways to half-ignore or fully-ignore ;-).

	To untrack a tracked file, without removing it from the
	working tree, "git rm --cached <file>" can be used.  To keep
	the file ignored after doing so, make sure that `.gitignore`
	knows that the file is to be ignored (e.g. by adding <file>
	to `.gitignore`, but you may already have a pattern that
	match <file> there).

Having commented on this section, I am not sure why we need so much description here, instead of clarifying the existing documentation of the mechanism in the Documentation/gitignore.txt file.

I think it is better to limit the FAQ list to two kinds of entries:

 * A topic that spans multiple mechanisms and features that is not
   easy to explain in a single documentation page may have to be
   described in place.

 * Other topics that already have authoritative description with
   adequate clarity in other pages should just have a summary
   paragraph that is less than 5 sentences, and a pointer to the
   authoritative page.

The `.gitignore` topic should fall into the latter category. It is a separate issue if Documentation/gitignore.txt has rooms for improvement and if so, I think it is more productive to propose a patch to it there, not adding too much description on the topic here.

Thanks.