[PATCH v3] Docs: git checkout --orphan: `root commit' and `branch head'
See:
Re: Can a git changeset be created with no parent
Carlos Martín Nieto <cmn@elego.de>
Message-ID: <1317073309.5579.9.camel@centaur.lab.cmartin.tk>
http://article.gmane.org/gmane.comp.version-control.git/182170
and:
git help glossary
Signed-off-by: Michael Witten <mfwitten@gmail.com>
---
Documentation/git-checkout.txt | 65 +++++++++++++++++++++++++++------------
1 files changed, 45 insertions(+), 20 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt
index c0a96e6..0b6e528 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,54 @@ explicitly give a name with '-b' in such a case.
below 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.
+--orphan::
+ Tell git to turn the next commit you create into a root commit
+ (that is, a commit without any parent); creating the next commit
+ is similar to creating the first commit after running "git{nbsp}init",
+ except that the new commit will be referenced by the branch head
+ <new_branch> rather than "master".
++
+Furthermore, the working tree and index are adjusted as if you ran
+"git{nbsp}checkout{nbsp}<start_point>"; thus, by just running
+"git{nbsp}commit", you can create a root commit with a tree that is
+exactly the same as the tree of <start_point>.
++
+Naturally, before creating the commit, you may manipulate the index
+in any way you want. For example, if you want to create a root commit
+with a tree that is totally different from the tree of <start_point>,
+then just clear the working tree and index first: From the top level
+of the working tree, run "git{nbsp}rm{nbsp}-rf{nbsp}.", and then
+prepare your new working tree and index as desired.
++
+There are two common uses for this option:
++
+--
+ Separate history::
+ Suppose that for convenience, you want to maintain
+ the website for your project in the same repository
+ as the project itself. In such a case, it may not
+ make much sense to interleave the history of the
+ website with the history of the project; you can use
+ the "--orphan" option in order to create these two
+ completely separate histories.
+
+ Hidden history::
+ Suppose you have a project that has proprietary
+ material that is never meant to be released to the
+ public, yet you now want to maintain an open source
+ history that may be published widely.
++
+In this case, it would not be enough just to remove the proprietary
+material from the working tree and then create a new commit, because
+the proprietary material would still be accessible through the new
+commit's ancestry; the proprietary history must be hidden from the new
+commit, and the "--orphan" option allows you to do so by ensuring that
+the new commit has no parent.
++
+However, removing proprietary material from ancestry is usually a task
+that is better performed by linkgit:git-filter-branch[1] and
+linkgit:git-rebase[1], especially when there are multiple commits that
+are already suitable for the open source history.
+--
-m::
--merge::
--
1.7.6.409.ge7a85
Michael Witten <mfwitten@gmail.com>