Michael Witten [off-list ref] writes:
See:
Re: Can a git changeset be created with no parent
Carlos Martín Nieto [off-list ref]
Message-ID: [off-list ref]
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.
quoted hunk
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.
On Wed, 28 Sep 2011 13:34:22 -0700, Junio C Hamano wrote:
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.
quoted
...
+--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?
I think it's absolutely necessary, but I'm not sure about how fragile
asciidoc is across versions with regard to this... I guess I'll remove
them.
quoted
+ 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>?
I took the "<new_branch>" from the synopsis:
SYNOPSIS
--------
[verse]
'git checkout' [-q] [-f] [-m] [<branch>]
'git checkout' [-q] [-f] [-m] [--detach] [<commit>]
'git checkout' [-q] [-f] [-m] [[-b|-B|--orphan] <new_branch>] [<start_point>]
'git checkout' [-f|--ours|--theirs|-m|--conflict=<style>] [<tree-ish>] [--] <paths>...
'git checkout' [-p|--patch] [<tree-ish>] [--] [<paths>...]
It would seem strange to include "<new_branch>" but not "<start_point>"
in each of the individual option descriptions.
In any case, I think we should leave that for another patch.
Moreover, I think it would be better to remove all `-h' output from
all git commands; they are always incomplete and/or different. Indeed,
at this point in history, programmers absolutely stink at writing
documentation, so it's probably a good idea just to centralize all
information as much as possible. Of course, I realize this suggestion
will never fly.
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.
I have qualms with git's terminology, and using "branch head" as I have is
not only the closest thing to what I like, but it is also the only language
that is actually in complete agreement with git's own terminolgy as currently
defined by "git help glossary".
In the glossary, the term "branch name" only occurs once as part of:
branch named "master"
which is undefined.
However, how skirting the whole issue:
except that the new commit will be referenced by <new_branch>
rather than "master".
quoted
+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.
"Naturally" reassures the reader that nothing really special is happening
in terms of how the next commit can be made; there are no special cases.
"Alternatively" is too strong; these 2 paragraphs are not mutually
exclusive: The bit about running just "git commit" is only a
clarification of the preceding sentence.
Nevertheless, I have rearranged the text to use "Alternatively" in
[PATCH v4]:
Message-ID: [off-list ref]
Subject: [PATCH v4] Docs: git checkout --orphan: Copyedit,
and s/root commit/orphan branch/
It should be a reply to this email.
quoted
+... 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".
I was thinking of something like git's repo's "man", "html", and "todo",
but I was trying to express that along the lines of a more widely
recognizable scenario.
See [PATCH v4] for a more generic version.
quoted
+ 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.
quoted
+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?
Yes. Have you no faith in me?
quoted
+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".
...
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.
I don't really see how what I wrote is fundamentally different. However,
I've rearranged it in [PATCH v4].
quoted
See:
Re: Can a git changeset be created with no parent
Carlos Mart=C3=ADn Nieto [off-list ref]
Message-ID: [off-list ref]
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.
What's your point?
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.
That's a good rule of thumb. Although, interestingly, one my last code
patches for git was accompanied by a very detailed, precisely formulated
description of the problem and the solution, and yet it was dumbed down
behind my back.
In this case, though, I think the message title gives enough information,
particularly when combined with the diff: It's a commit that alters the
documentation for "git checkout --orphan", and somehow involves the terms
"root commit" and "branch head" (though no longer in [PATCH v4]); the rest
of the log message is just meant to be cake icing for the interested.
It's copyediting; it's best just to read the damn patch, particularly when
there are no subtle details to be considered beyond the exhausting game of
making everybody involved in the email thread feel like he or she has gotten
a portion of the bikeshed painted a certain color.
Hmmm... You know what? I think I'll make that last paragraph the message.
Sincerely,
Michael Witten
From: "Michael Witten" <redacted>
quoted hunk
It's copyediting; it's best just to read the damn patch, particularly when
there are no subtle details to be considered beyond the exhausting game of
making everybody involved in the email thread feel like he or she has
gotten
a portion of the bikeshed painted a certain color.
See:
Re: Can a git changeset be created with no parent
Carlos Martín Nieto [off-list ref]
Message-ID: [off-list ref]
Signed-off-by: Michael Witten <redacted>
---
Documentation/git-checkout.txt | 69
++++++++++++++++++++++++++++-----------
1 files changed, 49 insertions(+), 20 deletions(-)
diff --git a/Documentation/git-checkout.txt
b/Documentation/git-checkout.txt
index c0a96e6..bf042c2 100644
--- a/Documentation/git-checkout.txt
+++ b/Documentation/git-checkout.txt
@@ -125,29 +125,58 @@ 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::
+ Perform these two tasks:
++
+--
+ * Adjust the working tree and index as if you ran
+ "git checkout <start_point>".
+
+ * Set up 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 init",
+ except that the new commit will be referenced by <new_branch>
+ rather than "master".
+--
++
+Then, by just running "git commit", you can create a root commit
+with a tree that is exactly the same as the tree of <start_point>.
+Alternatively, before creating the commit, you may manipulate the
+index in any way you want; for example, to create a root commit with
+a tree that is totally different from the tree of <start_point>,
+just clear the working tree and index first: From the top level of
+the working tree, run "git rm -rf .", and then prepare your new
+working tree and index as desired.
++
+There are two common uses for this option:
++
+--
+ Separate history::
Can I suggest "Distinct History::" as this title.
'separate' is both a verb and a noun, and it is easy to misread the title as
if it is the verb, which would then be describing the action of creating the
hidden history (the second title), with resulting misunderstanding.
"Distinct" avoids the problem. The use of 'seperate' at the end is in
context, so not an issue.
+ Suppose that for convenience, you want to maintain
+ in the same repository as your project some ancillary
+ material that is infrequently altered. In such a case,
+ it may not make much sense to interleave the history of
+ that material with the history of your project; you can
+ use the "--orphan" option in order to create 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, when there are multiple commits that are already suitable for
+the open source history (or that you want to make suitable), you should
+instead consider working with linkgit:git-filter-branch[1] and possibly
+linkgit:git-rebase[1].
+--
-m::
--merge::
--
1.7.6.409.ge7a85