From: Junio C Hamano <gitster@pobox.com>
Date: Mon, 21 Jun 2010 13:02:42 +0000 (-0700)
Subject: Merge branch 'jn/checkout-doc'
X-Git-Tag: v1.7.2-rc0~35
X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/f28f04923e87f88b4692a0718cc1207b41774d43?hp=-c

Merge branch 'jn/checkout-doc'

* jn/checkout-doc:
Documentation/checkout: clarify description
Documentation/checkout: clarify description
---

f28f04923e87f88b4692a0718cc1207b41774d43
diff --combined Documentation/git-checkout.txt
index 1548312b35,69cf917840..261dd90c38
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@@ -9,39 -9,47 +9,47 @@@ SYNOPSI
  --------
  [verse]
  'git checkout' [-q] [-f] [-m] [<branch>]
 -'git checkout' [-q] [-f] [-m] [-b <new_branch>] [<start_point>]
 +'git checkout' [-q] [-f] [-m] [[-b|--orphan] <new_branch>] [<start_point>]
  'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
  'git checkout' --patch [<tree-ish>] [--] [<paths>...]
  
  DESCRIPTION
  -----------
- 
- When <paths> are not given, this command switches branches by
- updating the index, working tree, and HEAD to reflect the specified
+ 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.
  
- 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.
+ 'git checkout' [<branch>]::
+ 'git checkout' -b <new branch> [<start point>]::
+ 
+ 	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 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.
  
- When <paths> 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 <tree-ish> (most often a commit).  In
- this case, the `-b` and `--track` options are meaningless and giving
- either of them results in an error. The <tree-ish> 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] [<tree-ish>] [--] <pathspec>...::
  
- 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
+ 	When <paths> 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 <tree-ish> (most often a commit).  In
+ 	this case, the `-b` and `--track` options are meaningless and giving
+ 	either of them results in an error. The <tree-ish> 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 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
  -------
@@@ -90,31 -98,6 +98,31 @@@ explicitly give a name with '-b' in suc
  	Create the new branch's reflog; see linkgit:git-branch[1] for
  	details.
  
 +--orphan::
 +	Create a new 'orphan' branch, named <new_branch>, started from
 +	<start_point> and switch to it.  The first commit made on this
 +	new branch will have no parents and it will be the root of a new
 +	history totally disconnected from all the other branches and
 +	commits.
 ++
 +The index and the working tree are adjusted as if you had previously run
 +"git checkout <start_point>".  This allows you to start a new history
 +that records a set of paths similar to <start_point> by easily running
 +"git commit -a" to make the root commit.
 ++
 +This can be useful when you want to publish the tree from a commit
 +without exposing its full history. You might want to do this to publish
 +an open source branch of a project whose current tree is "clean", but
 +whose full history contains proprietary or otherwise encumbered bits of
 +code.
 ++
 +If you want to start a disconnected history that records a set of paths
 +that is totally different from the one of <start_point>, then you should
 +clear the index and the working tree right after creating the orphan
 +branch by running "git rm -rf ." from the top level of the working tree.
 +Afterwards you will be ready to prepare your new files, repopulating the
 +working tree, by copying them from elsewhere, extracting a tarball, etc.
 +
  -m::
  --merge::
  	When switching branches,
@@@ -161,10 -144,6 +169,10 @@@ edits from your current working tree
  As a special case, the `"@\{-N\}"` syntax for the N-th last branch
  checks out the branch (instead of detaching).  You may also specify
  `-` which is synonymous with `"@\{-1\}"`.
 ++
 +As a further special case, you may use `"A...B"` as a shortcut for the
 +merge base of `A` and `B` if there is exactly one merge base. You can
 +leave out at most one of `A` and `B`, in which case it defaults to `HEAD`.
  
  <new_branch>::
  	Name for the new branch.