[PATCH] Documentation/git-checkout.txt: Explain --orphan without introducing an undefined "orphan branch"
- From
Junio C Hamano <gitster@pobox.com>
- Date
- Sep 29, 2011, 18:59 UTC
- Message-ID
- <7v39fftbt0.fsf@alter.siamese.dyndns.org>
- In-Reply-To
- <7vmxdnte0j.fsf@alter.siamese.dyndns.org>
The name of the `--orphan` option to `checkout` is meant to express that the next commit made on the branch does not have any parent (specifically, it will not be a child of the current nor start_point commit), but the glossary calls such a commit 'a root commit'. The explanation however used an undefined term 'orphan branch', adding mental burden to the first time readers.
Reword the description to clarify what it does without introducing a new term, stressing that it is similar to what happens to the "master' branch in a brand new repository created by `git init`. Also explain that it is OK to tweak the index and the working tree before creating a commit.
Also mildly discourage the users from using this to originate a new root commit that tracks material that is unrelated to the main branches in a single repository with a working tree, and hint a better way of starting an unrelated history, as it seems to be a common abuse of this option.
We may want to give a synonym `--new-root` to this option and eventually deprecate the `--orphan` option, as "parent vs orphan" might not immediately "click" to non native speakers of English (like myself), but that is a separate topic.
Signed-off-by: Junio C Hamano <gitster@pobox.com> ---
* I am inclined to suggest doing something like this instead.
Documentation/git-checkout.txt | 26 ++++++++++++++------------ 1 files changed, 14 insertions(+), 12 deletions(-)
diff --git a/Documentation/git-checkout.txt b/Documentation/git-checkout.txt index c0a96e6..63d164e 100644 --- a/Documentation/git-checkout.txt +++ b/Documentation/git-checkout.txt @@ -125,16 +125,16 @@ 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. + Adjust the working tree and the index as if you checked out the + <start_point>. The next commit begins a history that is not connected + to any other branches, as if you ran `git init` in a new repository, + except that the commit will be made on the <new_branch> branch, not on + the "master" branch. + -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. +Running "git commit" immediately after doing this will record a root commit +with a tree that is the same as the tree of the <start_point>. You may +manipulate the index before creating the commit to record a tree that is +different from that of the <start_point>. + 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 @@ -143,11 +143,13 @@ 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. +that is totally different from the one of <start_point>, you could +clear the index and the working tree right after "git checkout --orphan" +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. +However, such a use case to keep track of a history that is unrelated to +the main project is better done by starting a new, separate repository. -m:: --merge::