[PATCH] Attempt to make git-checkout man page a bit more clear.
From: Sean <hidden>
Date: 2016-06-15 22:42:46
Subsystem:
documentation, the rest · Maintainers:
Jonathan Corbet, Linus Torvalds
Signed-off-by: Sean Estabrooks <redacted> --- Documentation/git-checkout.txt | 40 +++++++++++++++++++++++++++------------- 1 files changed, 27 insertions(+), 13 deletions(-) A recent question on another list, quoted below, shows a new git user getting stuck on something pretty simple:
quoted
I'm after all the source of the drm 2.3.0 release. How do I use git to get all the source that drm-2.3.0 tags? I need the kernel drivers as well as the user land code so the tarball is no use to me. All the git docs tell me how to create a tag, but I have not found a single use show how to get a tree of files that correspond to a tag.
Hopefully this patch is accurate and would help a bit. Sean
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index fbdbadc..97c3afe 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt@@ -8,23 +8,29 @@ git-checkout - Checkout and switch to a branch SYNOPSIS -------- [verse] -'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<branch>] +'git-checkout' [-f] [-m] <branch> +'git-checkout' [-f] [-b <new_branch> [-l]] [-m] [<commit-ish>] 'git-checkout' [-m] [<branch>] <paths>... DESCRIPTION ----------- -When <paths> are not given, this command switches branches by -updating the index and working tree to reflect the specified -branch, <branch>, and updating HEAD to be <branch> or, if -specified, <new_branch>. Using -b will cause <new_branch> to -be created. - -When <paths> are given, this command does *not* switch -branches. It updates the named paths in the working tree from -the index file (i.e. it runs `git-checkout-index -f -u`). In -this case, `-f` and `-b` options are meaningless and giving -either of them results in an error. <branch> argument can be +Checkout the given branch, populating your working tree with its +contents. In the first form listed above, this command only +allows you to checkout an existing branch, not an arbitrary point +from the history. You can use the git-branch command to create +such branches. + +The second form of the command allows you to create a new branch +and check it out in one step. You specify the new branch name +with the "-b" option, followed by a reference to the commit that +will become the HEAD of the new branch. Note that you can specify +this commit by tag name, an existing branch name, or any other +reference specification git allows. + +With the third form, this command does *not* switch branches. +Instead, it replaces the contents of the named paths in your +working tree from the index. Here, the <branch> argument can be used to specify a specific tree-ish to update the index for the given paths before updating the working tree.
@@ -32,7 +38,8 @@ given paths before updating the working tree. OPTIONS ------- -f:: - Force a re-read of everything. + Force a switch to the given branch even when uncommitted + changes in your working tree will be lost as a result. -b:: Create a new branch named <new_branch> and start it at
@@ -92,6 +99,13 @@ You should instead write: $ git checkout -- hello.c ------------ +. To create a branch based on the contents marked by a given tag +and check it out in a single step: ++ +------------ +$ git checkout -b newbranch tag1.2.3 +------------ + . After working in a wrong branch, switching to the correct branch would be done using: +
--
1.4.4.2.g8336