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

[Junio C Hamano <gitster@pobox.com>]

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

> +[[rebasing-and-merging]]
> +How do I know when to merge or rebase?::
> +	Rebasing and merging two entirely different concepts with different utiilites.

Can you wrap these lines at a more reasonable column, like 65-72?

> +	In Git terms, rebasing means to place changes made in one branch over another branch
> +	(called base, hence the term rebase). The commit history of the branch wanting to rebase
> +	get placed over the branch on the receiving end and it appears as if those changes took
> +	place in the receiving branch itself. Merging, as the name suggests, merges the latest
> +	commit of one branch onto the recent branch, making this combination appear as one separate
> +	commit.

There is nothing technically wrong per-se in the above, but is this
worth saying here, instead of polishing the tutorial or rebase/merge
manual pages?  Also, in the above, I do not see much that would help
readers to decide which one between merge and rebase to choose.

> +[[files-in-.gitignore-are-tracked]]
> +I asked Git to ignore various files, yet they show up as changes in my staging area::
> +	One uses `.gitignore` to ignore files from getting tracked in the working tree. This ignores
> +	the aforementioned files for the whole lifetime of the project unless they area removed from
> +	the `.gitignore`.

This should mention "git add" (and possibly "git status") somewhere.
You list patterns to match cruft you want to "IGNORE", (i.e. would
not want to track), so that "git add ." would ignore it, and "git
status" won't make noises about them not being tracked.

> But, `.gitignore` will only ignore the files which were not a part of the
> +	repository when they were mentioned in the `.gitignore`. Hence, addition of a file to `.gitignore`
> +	after it was added to the working tree will have no effect and Git will keep tracking them.
> +	To prevent this from happening, one has to use `git rm --cached <file>` to remove the file
> +	from the staging area(i.e. the cache) and not from the repository. 

That's not "prevent this from happening".  It is more like
recovering from an earlier mistake of adding what you did not want
to add.

But people ask ".gitignore does not ignore, my vendor.o file is
tracked, and I want changes to vendor.o to be ignored" in the
context of "once tracked, .gitignore would ont kick in", so the
above advice to "remove from the tracked set" would not even help
them.  Their expectation needs to be adjusted, and an entry in FAQ
you are trying to add is a good place to do so.

> +[[checking-out]]
> +What is checking out a commit/branch? How do I perform one?::
> +	In Git terminology, checking out means updating the current working tree with a another commit or
> +	even a separate tree(which would translate to a branch).

Unless you are going to mention "switch" and "restore", you should
stress the fact that "checkout" checks out two separate things for
two different purposes upfront, in the first sentence.

 - Checking out a branch (or a commit) is to set up the working tree
   files in preparation for working on the history of the branch
   (most often, to grow the history by adding more commits, but
   sometimes to edit the history by rebasing).

 - Checking out individual paths out of a tree-ish (most often, a
   commit) is to grab a verbatim copy of the path recorded in the
   tree-ish to update the files in the working tree, and is done to
   work on the history of the current branch.

People found the "checkout" command confusing, as the distinction
between the two weren't clearly taught to them.  More recent
versions of Git introduced "switch" and "restore" subcommands that
can be used only for the former and for the latter purpose,
respectively.

Thanks.