Documentation: alter checkout --orphan description
The present text is a try to enhance description accuracy. It is a merge of the rewritten text made by native english speaker Chris Johnsen and further changes of Junio. It came from the last thread messages of --orphan patch. Signed-off-by: Erick Mattos <erick.mattos@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Erick Mattos committed
May 21, 2010 at 21:28 UTC
feb98d134289527eeb9d1fd11d8c284819a0aa1d
1 file changed
+21
-14
Documentation/git-checkout.txt
+21
-14
@@ -91,22 +91,29 @@ explicitly give a name with '-b' in such a case.
91
details.
92
93
--orphan::
94
- Create a new branch named <new_branch>, unparented to any other
95
- branch. The new branch you switch to does not have any commit
96
- and after the first one it will become the root of a new history
97
- completely unconnected from all the other branches.
94
+ Create a new 'orphan' branch, named <new_branch>, started from
95
+ <start_point> and switch to it. The first commit made on this
96
+ new branch will have no parents and it will be the root of a new
97
+ history totally disconnected from all the other branches and
98
+ commits.
99
+
99
-When you use "--orphan", the index and the working tree are kept intact.
100
-This allows you to start a new history that records set of paths similar
101
-to that of the start-point commit, which is useful when you want to keep
102
-different branches for different audiences you are working to like when
103
-you have an open source and commercial versions of a software, for example.
100
+The index and the working tree are adjusted as if you had previously run
101
+"git checkout <start_point>". This allows you to start a new history
102
+that records a set of paths similar to <start_point> by easily running
103
+"git commit -a" to make the root commit.
104
+
105
-If you want to start a disconnected history that records set of paths
106
-totally different from the original branch, you may want to first clear
107
-the index and the working tree, by running "git rm -rf ." from the
108
-top-level of the working tree, before preparing your files (by copying
109
-from elsewhere, extracting a tarball, etc.) in the working tree.
105
+This can be useful when you want to publish the tree from a commit
106
+without exposing its full history. You might want to do this to publish
107
+an open source branch of a project whose current tree is "clean", but
108
+whose full history contains proprietary or otherwise encumbered bits of
109
+code.
110
++
111
+If you want to start a disconnected history that records a set of paths
112
+that is totally different from the one of <start_point>, then you should
113
+clear the index and the working tree right after creating the orphan
114
+branch by running "git rm -rf ." from the top level of the working tree.
115
+Afterwards you will be ready to prepare your new files, repopulating the
116
+working tree, by copying them from elsewhere, extracting a tarball, etc.
117
118
-m::
119
--merge::