See: Re: Can a git changeset be created with no parent Carlos Martín Nieto <cmn@xxxxxxxx> Message-ID: <1317073309.5579.9.camel@xxxxxxxxxxxxxxxxxxxxxx> http://article.gmane.org/gmane.comp.version-control.git/182170 and: git help glossary Signed-off-by: Michael Witten <mfwitten@xxxxxxxxx> --- 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 -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html