Hi, 2010/3/22 Chris Johnsen <chris_johnsen@xxxxxxxxx>: > On 2010 Mar 21, at 10:34, Erick Mattos wrote: >> >> Similar to -b, --orphan creates a new branch, but it starts without any >> commit. After running "git checkout --orphan newbranch", you are on a >> new branch "newbranch", and the first commit you create from this state >> will start a new history without any ancestry. >> >> "git checkout --orphan" keeps the index and the working tree files >> intact in order to make it convenient for creating a new history whose >> trees resemble the ones from the original branch. >> >> When creating a branch whose trees have no resemblance to the ones from >> the original branch, it may be easier to start work on the new branch by >> untracking and removing all working tree files that came from the >> original branch, by running a 'git rm -rf .' immediately after running > > Maybe use double quotes in the above command to be consistent with the rest > of inline commands in the commit message. > >> "checkout --orphan". >> >> Signed-off-by: Erick Mattos <erick.mattos@xxxxxxxxx> >> --- > >> diff --git a/Documentation/git-checkout.txt >> b/Documentation/git-checkout.txt >> index 37c1810..5a50997 100644 >> --- a/Documentation/git-checkout.txt >> +++ b/Documentation/git-checkout.txt > >> @@ -90,6 +90,25 @@ explicitly give a name with '-b' in such a case. >> Create the new branch's reflog; see linkgit:git-branch[1] for >> details. >> >> +--orphan:: >> + Create a new branch named <new_branch>, unparented to any other >> + branch. The new branch you switch to does not have any commit >> + and after the first one it will become the root of a new history >> + completely unconnected from all the other branches. >> ++ >> +When you use "--orphan", a new unparented branch is created having the >> +index and the working tree intact. This allows you to start a new >> +history that records set of paths similar to that of the start-point >> +commit, which is useful when you want to keep different branches for >> +different audiences you are working to like when you have an open source >> +and commercial versions of a software, for example. >> ++ >> +If you want to start a disconnected history that records set of paths >> +totally different from the original branch, you may want to first clear >> +the index and the working tree, by running "git rm -rf ." from the >> +top-level of the working tree, before preparing your files (by copying >> +from elsewhere, extracting a tarball, etc.) in the working tree. >> + >> -m:: >> --merge:: >> When switching branches, > > (American) English is my first language, but that does not imply that I > speak, read, or write perfectly. > > "unparented" sounds a bit awkward to me. > > "unconnected from all": the usual constructions are "unconnected to", > "connected to" or "disconnected from"; might be better as "disconnected from > all" or "not connected to any" > > "unparented" sounds odd to me, especially "unparented to". For "unparented > branch", I would use "branch without parents", maybe "history-free branch". > > I think the repeated uses of "unparented" in the first and second > paragraphs, and its description can be coalesced into the the first > paragraph, leaving the later paragraphs to describe the "common paths" and > "no common paths" cases. > > The second sentence of the second paragraph seems overly long and gets a bit > muddled near the end. I can not parse "audiences you are working to". Maybe > it should be "audiences you are working with" or "... for"? > > In the third paragraph, "first clear the index and the working tree" bit > could be taken to mean "clear the index and working tree before creating the > new branch" (which might work, but leaves a possibly confusing state if the > user is distracted between "rm -rf" and "checkout --orphan" (still on the > original branch, the deletion of everything has been staged)). Also, use > backquotes to properly format the example command. > > Here is my take on these paragraphs: > > -->8---->8-- > --orphan:: > Create a new, 'orphan' branch named <new_branch>, and start it > at <start_point>. The first commit made on this new branch will > have no parents (it will be the root of a new history that is > not connected to any the other branches or commits). > + > An orphan branch allows you to start a new history that records a set of > paths similar to <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 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 <start_point>, you may want to clear the > index and the working tree after creating the orphan branch. > Run `git rm -rf .` from the top level of the working tree, then prepare > your new files by copying them from elsewhere, extracting a tarball, or > otherwise populating the working tree. > --8<----8<-- > > -- > Chris > I am in favor of changing the whole texts to your versions. Let's wait for Junio's opinion. After this wonderful English and modesty lessons, I started thinking: since Git is a worldwide spread software why it is not using gettext to have its translations? It would not be a hard job because gettext separates the job of translation from normal work flow with just minor changes to inline message constants. Best regards to all -- 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