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

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

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

> +[[checking-out]]

> +What is checking out a commit/branch? How do I perform one?::

> +	In Git terminology, a 'checkout' serves three purposes, namely:

Well, whoever is asking the question knows what s/he wants to do is
to check out a commit/branch and not "grab a version of files from
different tree", so this is answering a question that is not asked.

Teaching the distinction of two kinds of checkout [*] may be
important, but then we should do so by answering a different
question ;-)

	Side note.  There are not three but two variants.  There is
	no conceptual difference between checking out a branch and
	moving to detached HEAD.  They are both to prepare extending
	the history that led to the commit (either the commit that
	was checked out, or the commit at the tip of the branch that
	was checked out); what is done to the resulting history is
	the only difference (if you work on detached HEAD, you can
	decide which branch to update with after you are finished
	working, if you stay on a branch, you are committed to
	update that branch at the time of checking it out).

> +		1. Go to another commit; I would be "checking out"
> +		to that commit and enter a "detached HEAD" state,

"Check out" is a direct verb, i.e. "check out the commit", not
"check out to the commit".  The same thing can be said to other uses
in your document about checking out a path out of a tree-ish.

> +		meaning, that the "pointer" called HEAD which tells
> +		me where I am right now in my working tree is not
> +		where it generally should be, i.e., referring to a
> +		named branch(say, master).  Instead the
> +		aforementioned pointer is referring to the specified
> +		commit. I can now work upon the checked out commit
> +		and make any changes or just inspect the files at
> +		that state.
> +
> +		2. Go to a different version of a particular file;

Who is "going" and where?  Isn't it easier to understand if you
explained that "checking out a path out of a tree-ish" is to grab a
copy of the blob (which is at the path in the tree-ish) and update
the working tree with it?  "Replace a file in the working tree with
the same file in a different commit", perhaps?

> +		let's say I want to go to a particular version of a

"go to" -> "have" would make this understandable, at least to me.

> +		file in my working tree. I can again "checkout" to
> +		that particular version(i.e., going to a particular
> +		commit where certain changes were made). This can be
> +		done by entering the SHA1 of the commit in question.
> +
> +		3. Go to another branch or create another branch; I
> +		would be "checking out" to another tree in my local
> +		repository. One might expect to enter a detached
> +		HEAD here as well but in fact does not.

It is unclear why one would expect such a behaviour.  Is this really
a frequently asked question?

> +             This is
> +		because HEAD would point to the tip of the checked
> +		out branch, something which is not a characteristic
> +		of a detached HEAD.

> ++
> +To checkout to a commit, one can either pass the SHA1 of the
> +commit to be checked out or a reference to it w.r.t.  the HEAD.

I do not know what you mean by "or a reference to it w.r.t the
HEAD" here..

> +To checkout to a particular version of a file, one can use `git
> +checkout <SHA1/reference> <file>`.  

You are getting confused here.  This part belogs to #2 above,
i.e. grabbing a path out of a tree-ish as a way to help growing the
current line of the history (either branch or the detached HEAD) you
are working on.  Not an appropriate sentence to have in the section
for #3, which is about switching the line of history you are going
to grow.

> + To checkout to an already
> +existing branch, one should use `git checkout <branch-name>`. To
> +simultaneously create and checkout to a branch, one can use the
> +`-b` option in the aforementioned command.

Yes.  But drop "to" from "check out to".  You "check out a branch",
not "check out to a branch".

> +One can observe how versatile the checkout command is, yet due to
> +simplify things even further, two commands were introduced in
> +version 2.23 of Git so as to break down the functionalities of
> +`git checkout` and make it learning the command easier for a
> +beginner.

Drop "even further".  A common complaint was that it was too
versatile and introducing two separate commands for its two (again,
not three) uses was done to make it simpler and easier to learn and
use.

> +The commands being `git switch` and `git restore`.
> ++
> +`git restore` combines the first two features of the checkout as
> +well as functionalities of `git reset` and `git revert` at one
> +place so as to improve the functionality of the command.

Are you sure?  I thought you artificially split "switch" into #1
(switch to a detached HEAD) and #3 (switch to a branch) and
described "check out paths out of tree-ish to the working tree" as
#2, which is what "git restore" is.

> +`git switch` perfoms the third functionality of the `git checkout`
> +command, i.e., manipulating branches(creation).

Ditto.  Detach, orphan, creation, and plain branch switching all
fall into "switch"'s purview.

The distinction to keep in mind is if you are checking out a line of
history to work on, or if you are sticking to the current line of
history and manipulating working tree files by grabbing contents of
paths out of a different tree-ish.

Again, I am not sure why we need to have separate description about
two primary modes of "git checkout" here, instead of making sure we
have serviceable explanation in "git checkout" manual page and point
it from here, if "what are two modes of checkout?" is a frequently
asked question.  For those who started their Git experience with
"switch" and "restore" without touching "checkout", the distinction
may not even have to be explained.

Thanks.