From c5b41519c723ec1966e5f2d6326862095bfa7bb8 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Sun, 30 May 2010 03:41:53 -0500 Subject: Documentation/checkout: clarify description MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit To the first-time reader, it may not be obvious that ‘git checkout’ has two modes, nor that if no branch is specified it will read from the index. Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-checkout.txt | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index 37c1810e3f..acbc2d53ed 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -15,26 +15,32 @@ SYNOPSIS DESCRIPTION ----------- +Retrieves files from the index or specified tree and writes them +to the working tree. -When are not given, this command switches branches by -updating the index, working tree, and HEAD to reflect the specified -branch. +'git checkout' [-b ] []:: + When are not given, this command switches branches by + updating the index, working tree, and HEAD to reflect the + specified branch. ++ If `-b` is given, a new branch is created and checked out, as if linkgit:git-branch[1] were called; in this case you can use the --track or --no-track options, which will be passed to `git branch`. As a convenience, --track without `-b` implies branch creation; see the description of --track below. -When or --patch are given, this command does *not* switch -branches. It updates the named paths in the working tree from -the index file, or from a named (most often a commit). In -this case, the `-b` and `--track` options are meaningless and giving -either of them results in an error. The argument can be -used to specify a specific tree-ish (i.e. commit, tag or tree) -to update the index for the given paths before updating the -working tree. +'git checkout' [--patch] [] [--] [...]:: + When or --patch are given, this command does *not* switch + branches. It updates the named paths in the working tree from + the index file, or from a named (most often a commit). In + this case, the `-b` and `--track` options are meaningless and giving + either of them results in an error. The argument can be + used to specify a specific tree-ish (i.e. commit, tag or tree) + to update the index for the given paths before updating the + working tree. ++ The index may contain unmerged entries after a failed merge. By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. -- cgit v1.2.3 From b831deda174da7864ca5d529f53296af3f41ee18 Mon Sep 17 00:00:00 2001 From: Jonathan Nieder Date: Tue, 1 Jun 2010 02:25:23 -0500 Subject: Documentation/checkout: clarify description git checkout can be used to switch branches and to retrieve files from the index or an arbitrary tree. Split the description into subsections corresponding to each mode to make each use easier to understand. Helped-by: Jeff King Signed-off-by: Jonathan Nieder Signed-off-by: Junio C Hamano --- Documentation/git-checkout.txt | 40 +++++++++++++++++++++------------------- 1 file changed, 21 insertions(+), 19 deletions(-) diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index acbc2d53ed..69cf917840 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -15,39 +15,41 @@ SYNOPSIS DESCRIPTION ----------- -Retrieves files from the index or specified tree and writes them -to the working tree. +Updates files in the working tree to match the version in the index +or the specified tree. If no paths are given, 'git checkout' will +also update `HEAD` to set the specified branch as the current +branch. -'git checkout' [-b ] []:: +'git checkout' []:: +'git checkout' -b []:: - When are not given, this command switches branches by - updating the index, working tree, and HEAD to reflect the - specified branch. + This form switches branches by updating the index, working + tree, and HEAD to reflect the specified branch. + -If `-b` is given, a new branch is created and checked out, as if -linkgit:git-branch[1] were called; in this case you can -use the --track or --no-track options, which will be passed to `git -branch`. As a convenience, --track without `-b` implies branch -creation; see the description of --track below. +If `-b` is given, a new branch is created as if linkgit:git-branch[1] +were called and then checked out; in this case you can +use the `--track` or `--no-track` options, which will be passed to +'git branch'. As a convenience, `--track` without `-b` implies branch +creation; see the description of `--track` below. -'git checkout' [--patch] [] [--] [...]:: +'git checkout' [--patch] [] [--] ...:: - When or --patch are given, this command does *not* switch + When or `--patch` are given, 'git checkout' *not* switch branches. It updates the named paths in the working tree from - the index file, or from a named (most often a commit). In + the index file or from a named (most often a commit). In this case, the `-b` and `--track` options are meaningless and giving either of them results in an error. The argument can be used to specify a specific tree-ish (i.e. commit, tag or tree) to update the index for the given paths before updating the working tree. + -The index may contain unmerged entries after a failed merge. By -default, if you try to check out such an entry from the index, the +The index may contain unmerged entries because of a previous failed merge. +By default, if you try to check out such an entry from the index, the checkout operation will fail and nothing will be checked out. -Using -f will ignore these unmerged entries. The contents from a +Using `-f` will ignore these unmerged entries. The contents from a specific side of the merge can be checked out of the index by -using --ours or --theirs. With -m, changes made to the working tree -file can be discarded to recreate the original conflicted merge result. +using `--ours` or `--theirs`. With `-m`, changes made to the working tree +file can be discarded to re-create the original conflicted merge result. OPTIONS ------- -- cgit v1.2.3