Shourya Shukla <shouryashukla.oo@xxxxxxxxx> 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.
