Michael Witten <mfwitten@xxxxxxxxx> writes: > 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 I think I had to tell somebody on this list not to do this no more than a month ago. It is a good practice to point to earlier discussions while polishing patch, and it also is good to include pointers in the commit log message as a _supporting material_ (additional reading), but that is *NOT* a substitute for a properly written commit log message. You need to state what problem you are trying to fix and how the proposed patch fixes it. Pretty please. As to what the updated text wants to talk about, I think most of them are improvement, but there are a few glitches and nits. > 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", I do not think we ever used {nbsp} in our documentation set. Is it absolutely necessary to use it in this context, and are you absolutely sure this does not break various versions of documentation toolchain people have? > + except that the new commit will be referenced by the branch head > + <new_branch> rather than "master". The option works as a substitute for -B/-b in the sense that it takes a name of the new branch, and the only difference is that the new branch will start with no commit (yet). To reduce confusion, it might make sense to update this part (and description of -b/-B) to begin like this: --orphan <new_branch>:: to match the new explanation text, and the output from "git checkout -h". By the way, shouldn't the entry for -b in "git checkout -h" output also say <new branch>? Micronit: "referenced by the branch head <new_branch>" might be easier to read and understand with s/branch head/branch name/. Or perhaps except that the new commit will be made on <new_branch> branch rather than "master". might be even better. > ++ > +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. ... What value does "Naturally, " add to the understanding here? I would understand if it were "Alternatively, ", though. > +... 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. I suspect this is *not* common at all, and also because you would need a working tree to update both lines of histories that are not related to each other at all at the content level, I do not believe that "for convenience" supports or justifies the use case at all. It would be less convenient to update these two unrelated histories (switching between branches would need to nuke the whole working tree, and the semantics to carry local changes floating on top of the tip commit of the current branch across branch switching actively works against you). You would be better off using another repository to keep track of "the website for your project". In short, I do not think we would want to list the above as if we are somehow encouraging the use of this option for such a use. It falls into "because with --orphan you _could_", and definitely not "because having these two unrelated projects in the same repository you work in is convenient and/or necessary". > + 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. This cause does make sense; you would want the local changes floating on top of the tip commit of the current branch carried across branch switching. > +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. Does this "In this case" paragraph format as part of the "Hidden history" paragraph? > ++ > +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. > +-- In general it is true, and not "especially". When you are just abandoning the history and publishing tidied up tree without history afresh. I suspect this is not exactly "filter-branch is better but you could use checkout --orphan" like you made it sound in the above paragraph. If you are bootstrapping a new open source project from the tip of a proprietary tree, "checkout --orphan && edit to sanitize && commit" to start your history afresh would be perfectly adequate for your PR people to say "Now we are open", especially when you do not intend to accept fixes to older revisions; you could filter-branch the older proprietary history but you would not get much benefit out of the cost for doing so, I think. Thanks. -- 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