Erick Mattos [off-list ref] writes:
quoted
The use case in your commit log message wasn't convincing either. If such
a new branch will be merged later, especially if the trees of the commits
in newly rooted history resemble the trees in the original history (I am
guessing that is the intended use case, as you do not seem to be removing
anything from the working tree---how is the user expected to use them by
the way?), not having a common merge base will make the merge harder, not
easier, and later examination of the history (think "bisect") also
harder.
Are you talking about the commit log message of the previous version
patch?
I was referring to this from the latest version:
Sometimes it is necessary to start up a new development branch of code
intended to be merged in the near future to existing branches but which
actually does not relate to them.
Let's give you an example of the depth of thought and clarity of
description of the workflow I am expecting from anybody who claims "this
is a useful feature to help _some_ workflows" by taking an example from
git.git, because it is one project that both of us are familiar with and
there is a readily available example in it. It has disjoint merges from
gitk, gitweb and git-gui. The history up to such a merge 5569bf9 (Do a
cross-project merge of Paul Mackerras' gitk visualizer, 2005-06-22) looks
like this:
A---o---?---o---o---X---* linus
. /
B---o---o---Y gitk
Note that with this merge '*', two histories merged did not share any
paths at commit X and Y.
Did you have this kind of "no common paths" merge in mind when you wrote
the proposed commit log message? IOW, if we pretend that Paul started his
gitk work and he "intended to be merged to Linus's branch but which does
not relate to it", would that be a good example of what you are trying to
achieve?
Side note: The other two "disjoint" merges we have are also this kind
of "no common paths" merge. Nobody who was involved in the branches
that resulted in them prepared his branch with --orphan, by the way.
They started out in independent repositories, because they were by
definition independent projects and these were "cross project merges",
as Linus put it.
I'd grant you that we could say that these histories did not start in the
same repository using "checkout --orphan" because it was not available.
But in that case, it would have been nicer if Paul didn't have to remove
files came from Linus's branch, left by your "checkout --orphan", by hand.
"rm -rf" would not have been very useful, especially if he had some
untracked files that he never intended to commit to git project but did
not want to lose (think of "Notes" "memo" "todo" files you would keep in
the source tree). The most natural way to keep these untracked files
while removing now-unneeded tracked files in the Linus's git when he
switched from using "checkout --orphan" would have been to use something
like "ls-files -z | xargs -0 rm -f". But you are nuking the index without
removing the tracked files, so that becomes impossible.
On the other hand, Paul could have started his gitk branch from a copy of
git Linus had published. Even though gitk was developed with an intention
to run with any version of git available that was installed idependently
on the system, it did depend on git and it would have made equal amount of
sense if he shipped with a matching version of git, saying "this version
of gitk was tested with this git". If that were the case, paths at commit
X and Y would have been overlapping. In fact, gitk has been a single-file
project for a long time, so most of the paths were the same and Y would
had one file more than X.
Did you have this kind of "mostly common paths" merge in mind when you
wrote the proposed commit log message? IOW, if "checkout --orphan" were
available to Paul, would you have recommended him to use it, add his gitk
script to the tree, and start his history at commit B which he started
from commit '?' from Linus's history? But you are again nuking the index
so Paul would have had to add the files back with "git add", while being
careful not to add untracked files, or run "git read-tree ?" to populate
the index back to the original state.
I am not wiping the tree by default because I am not deciding for
people if they are going to use anything from it as a template (even
the directory structure only).
I am not trying to make decisions for the user. I think he would be
capable of deciding it himself. That is my way of thinking so I
normally prefer to advice, alert, inform not to impose.
You may think that you are supporting both, but in reality, you are
supporting neither by making both cases equally inconvenient. The only
thing you are gaining is a way to weasel out of issues experienced by the
users by saying "I didn't remove anything from the working tree, so if you
want to add them, you can, it is up to you", while ignoring the issue that
(1) if the user wants "no common paths", cleaning working tree becomes
cumbersome and error prone, and (2) if the user wants "mostly common
paths", adding back to the index becomes cumbersome and error prone.
As I already said, I do not think "mostly common paths" case should be
encouraged to begin with. As far as I know (and you can guess by now that
I know reasonably well about git), you do not gain anything by not having
the ancestry link between '?' and 'B', except that it would make conflict
resolution at '*' extremely difficult. There is only downside without any
upside in "mostly common paths" disjoint merge.
That leaves only the "almost no common paths" case. As we have already
seen in git project, the end result is indeed very useful. It used to be
that people had to download and use gitk independently before Linus's
cross project merge, but after the merge, the project gives the core git
and gitk comes with it. So you could argue that "checkout --orphan" would
become useful if you adjusted the code like I suggested in my review
comments (run an equivalent of "git rm" without "-f" from the top-level
and make the HEAD dangling to the new branch, only if the "git rm" step
succeeds), and document clearly that is the intended workflow for the new
feature to support.
But stepping back a bit, you would realize that the usefulness of the end
result of these existing "disjoint merges" does not come from the fact
that the side branch was initially a disjoint history from the main
branch. The usefulness of the end result comes solely from the fact that
we managed to merge such a side branch. If Paul started gitk by forking
Linus's git, adding gitk script, _without_ making the history disjoint,
the result of the merge would have been equally useful.
The only reason the early part of gitk's history is independent from git
is because Paul nor Linus did _not_ have any plan to merge these two
histories. Lack of foresight is not a crime, so it is perfectly fine if
you have to merge histories that started separately, but if you do plan to
merge the future, starting the branch as a disjoint history is a crime--it
does not help anybody.
Up to this point, I:
- described possible two workflows ("almost no common paths" and "mostly
common paths") that "checkout --orphan" _could_ support;
- explained why neither makes sene; and
- explained why your implementation does not support either one well,
even if one or both of these workflows made sense.
Now, do not take the above as a personal criticism. The only thing the
above discussion may be showing could be that your description was not
clear enough to tell me that the workflow you had in mind to support was a
third one, different from the above two, and that your implementation may
support that untold workflow very well. Take the above as an illustration
of how you present the workflow your new feature intends to support, and
how you choose your design and implementation to support that workflow
well.
So let's hear it. Until we clear the design issues, there is not much
point in talking about coding styles and implementation.
Junio C Hamano [off-list ref] writes:
As I already said, I do not think "mostly common paths" case should be
encouraged to begin with. As far as I know (and you can guess by now that
I know reasonably well about git), you do not gain anything by not having
the ancestry link between '?' and 'B', except that it would make conflict
resolution at '*' extremely difficult. There is only downside without any
upside in "mostly common paths" disjoint merge.
There is one case "mostly common paths" disjoint history can be useful.
Imagine you have a hitherto proprietary software project and want to go
open source. Perhaps your intention is to have an open source version and
an enhanced commercial version. The project contains some third-party
vendor software outside your control, and you have replaced them with open
source equivalents or disabled features that depend on them.
Your history may look like this:
o---o---A oss-base
/
---o---o---o---o master
where master is the primary version you will continue shipping to your
paying customers, with proprietary third-party components and features
that depend on them. Commits on oss-base were your work to prepare the
tree into a releasable shape, removing these proprietary stuff along with
some features.
But you cannot publish oss-base (commit A) to the public. "git log" will
show all the history that leads to it, with all the third-party stuff you
do not have license to distribute in the source form. The older parts of
the history may even have site password at customer installation you have
committed by mistake and eradicated long time ago.
If you run this three command sequence (in this message, I am assuming
that you keep the index and the working tree files intact in an updated
implementation of --orphan, which is different from the suggestion to
support "no common paths" case I mentioned in the previous message):
$ git checkout --orphan oss oss-base
$ git checkout oss-base
$ git merge -s ours oss
you will get a history of this shape:
X oss
\
o---o---A---B oss-base
/
---o---o---o---o master
with commits X, A and B all recording an identical tree. The oss branch
(commit X) is now safe to publish.
Once you have done this, further you can:
$ git checkout master
$ git merge oss-base
which gives you a history of this shape:
X oss
\
o---o---A---B oss-base
/ \
---o---o---o---o---Y master
This merge Y has to be done carefully. It inherently has to be an evil
merge because oss-base wants to replace some proprietary stuff with open
source counterparts while you may want to keep using the proprietary ones
you have support contract for in your paying customer release you will
make from the master branch. So at Y, you will most likely be reverting
some work you did on oss-base branch since it forked from master.
After setting it up, this arrangement allows you to:
- accept changes from public, and/or build changes for public, to advance
"community version" on the oss branch on top of X;
- from time to time, merge oss to oss-base;
- from time to time, merge oss-base to master.
and the histories will continue like this:
X---C---C---C---C oss
\ \
o---o---A---B-----------* oss-base
/ \ \
---o---o---o---o---Y---P---P---*---P---P master
with community commits C (either contributed from the public or you
developed yourself and gave to the community) on oss branch, with
proprietary commits P that record your own proprietary work on master
branch. Note that oss-base branch is not used to produce nor record any
commit on its own---it is merely to ease the merging from oss and master
by providing X-B link to serve as a convenient common ancestor to make
later merges easier.
Note also that it would be the most convenient if you kept both the index
and the working tree intact, if "checkout --orphan" is to be used as an
ingredient for this workflow. It _might_ actually make sense not to make
the "git checkout --orphan" an independent feature that can be randomly
abused or misused, but package the three-command sequence to create the
A-B-X open triangle above into a separate command, i.e.
$ git branch --orphan oss
would create a new branch "oss" with its own root commit X that records
the same tree as the current HEAD A, and immediately merge X back into A
to produce B, again recording the same tree, and advance the current HEAD
to point at B, like so:
X oss
\
---o---A HEAD --> ---o---A---B HEAD
Junio C Hamano [off-list ref] writes:
Side note: The other two "disjoint" merges we have are also this kind
of "no common paths" merge. Nobody who was involved in the branches
that resulted in them prepared his branch with --orphan, by the way.
They started out in independent repositories, because they were by
definition independent projects and these were "cross project merges",
as Linus put it.
Note that beside "disjoint" merges ("cross project merges"), of gitk,
git-gui, gitweb and (very early in git history) git mail tools, there
are also three "disjoint"/"unparented" branches: 'html', 'man' and
'todo'.
While 'todo' is totally unrelated, and if instead of starting in
separate repository it would be created using proposed feature, it
would be created with "no common paths" case.
BUT in the case of 'html' and 'man' branches I could see why current
implementation of _removing index and not removing files_ might be
advantageous. Remove index, create HTML and manpage version of
documentation, and add HTML (in 'html' branch) or manpages (in 'man'
branch)... probably shifting root, so it is not all in single
Documentation directory.
Just my 2 eurocents.
--
Jakub Narebski
Poland
ShadeHawk on #git
Hi,
Sorry for writing much again in reply.
2010/3/13 Junio C Hamano [off-list ref]:
I was referring to this from the latest version:
Sometimes it is necessary to start up a new development branch of code
intended to be merged in the near future to existing branches but which
actually does not relate to them.
That is one from some reasons to start a new empty, unparented,
unrelated, without ancestry branch. An example which is not
considered good enough by your opinion.
I am not trying because I don't feel myself good enough to convince
you of anything. But I will try to give you more examples at the end
of this reply.
To be more general the text could be:
Sometimes it is interesting to start an new unparented branch for new code.
Let's give you an example of the depth of thought and clarity of
description of the workflow I am expecting from anybody who claims "this
is a useful feature to help _some_ workflows" by taking an example from
git.git, because it is one project that both of us are familiar with and
there is a readily available example in it. It has disjoint merges from
gitk, gitweb and git-gui. The history up to such a merge 5569bf9 (Do a
cross-project merge of Paul Mackerras' gitk visualizer, 2005-06-22) looks
like this:
A---o---?---o---o---X---* linus
. /
B---o---o---Y gitk
Note that with this merge '*', two histories merged did not share any
paths at commit X and Y.
Did you have this kind of "no common paths" merge in mind when you wrote
the proposed commit log message? IOW, if we pretend that Paul started his
gitk work and he "intended to be merged to Linus's branch but which does
not relate to it", would that be a good example of what you are trying to
achieve?
I am not trying to achieve anything. I am already doing what I want
myself. I am just trying to let people achieve what they want without
a hack.
I think you haven't checked those, so PLEASE:
Git SCM Wiki:
http://git.wiki.kernel.org/index.php/GitTips#How_to_create_a_new_branch_that_has_no_ancestor
Git Book:
http://book.git-scm.com/5_creating_new_empty_branches.html
Anyway your example is a good one if you are the one which controls
the branch flows and know you will be doing the merge eventually. It
fits then on my explained case.
Side note: The other two "disjoint" merges we have are also this kind
of "no common paths" merge. Nobody who was involved in the branches
that resulted in them prepared his branch with --orphan, by the way.
They started out in independent repositories, because they were by
definition independent projects and these were "cross project merges",
as Linus put it.
They were not foreseeing the future but and if they were the only
developer and could project what they would need?
I'd grant you that we could say that these histories did not start in the
same repository using "checkout --orphan" because it was not available.
That's it!
Did you have this kind of "mostly common paths" merge in mind when you
wrote the proposed commit log message? IOW, if "checkout --orphan" were
available to Paul, would you have recommended him to use it, add his gitk
script to the tree, and start his history at commit B which he started
from commit '?' from Linus's history? But you are again nuking the index
so Paul would have had to add the files back with "git add", while being
careful not to add untracked files, or run "git read-tree ?" to populate
the index back to the original state.
He would use it easily. No difficulty at all.
I think the problem here is a matter of opinion: you think removal
should be automatically followed. Like 'git checkout -ob NEW_BRANCH'
followed by 'git clean -df'.
I don't. I think the user can do it or not by himself.
I am not trying to convince you. You rule.
quoted
I am not wiping the tree by default because I am not deciding for
people if they are going to use anything from it as a template (even
the directory structure only).
I am not trying to make decisions for the user. I think he would be
capable of deciding it himself. That is my way of thinking so I
normally prefer to advice, alert, inform not to impose.
You may think that you are supporting both, but in reality, you are
supporting neither by making both cases equally inconvenient. The only
thing you are gaining is a way to weasel out of issues experienced by the
users by saying "I didn't remove anything from the working tree, so if you
want to add them, you can, it is up to you", while ignoring the issue that
(1) if the user wants "no common paths", cleaning working tree becomes
cumbersome and error prone, and (2) if the user wants "mostly common
paths", adding back to the index becomes cumbersome and error prone.
Really?
(1) git clean -df
(2) git add WHATEVER
It does not look cumbersome or error prone to me. :-1
As I already said, I do not think "mostly common paths" case should be
encouraged to begin with. As far as I know (and you can guess by now that
I know reasonably well about git), you do not gain anything by not having
the ancestry link between '?' and 'B', except that it would make conflict
resolution at '*' extremely difficult. There is only downside without any
upside in "mostly common paths" disjoint merge.
I do not have to guess: you are the man. I know you know everything about git.
First of all, I do respect you a lot. Not only by all your knowledge,
or your commitment, or by Git's creator confidence upon you.
But more than all because of the hard work you have been giving to
this project. Time and effort are very rare commodities to be wasted
these days.
The problem here is not what you know. It is not about you. It is
about what Git should become to ease user's life. It is to pay
attention to common as well as to uncommon needs.
The first reason for Git was to be the Linux kernel SCM. That was
already achieved perfectly.
Git should freeze then?
Being good is not a reason for not becoming better. I am trying to
make it better by filling a gap. I have started my contributions by
filling needs I had which were not fulfilled.
We are not encouraging anything. We are just letting people do what
they want to. Having an empty new branch to start with is something
some people want to do. Please do the google search I told you
before: "new empty branch git".
And finally, remember, merge will be easy because unparented branch is
mainly for unrelated work. User will solve problems if he wants any
exotic stuff.
That leaves only the "almost no common paths" case. As we have already
seen in git project, the end result is indeed very useful. It used to be
that people had to download and use gitk independently before Linus's
cross project merge, but after the merge, the project gives the core git
and gitk comes with it. So you could argue that "checkout --orphan" would
become useful if you adjusted the code like I suggested in my review
comments (run an equivalent of "git rm" without "-f" from the top-level
and make the HEAD dangling to the new branch, only if the "git rm" step
succeeds), and document clearly that is the intended workflow for the new
feature to support.
The end result will be very helpful indeed.
You are thinking as a maintainer of a huge project with a lot of
merging. This new function is indeed not very useful to you. But it
is to people running different work flows. Most of all when they are
running small projects and when they have full control of the
repository without a lot of clones widespread.
Now, do not take the above as a personal criticism. The only thing the
above discussion may be showing could be that your description was not
clear enough to tell me that the workflow you had in mind to support was a
third one, different from the above two, and that your implementation may
support that untold workflow very well. Take the above as an illustration
of how you present the workflow your new feature intends to support, and
how you choose your design and implementation to support that workflow
well.
I am not taking anything personally. I already know your way of working.
But I have descripted what I wanted to. When I showed the
debianization case to picture it, that was something I did. Even
though you don't think is a good way to do it.
This new function satisfies a lot of needs because an empty new branch
is needed some times and the way to get it nowadays is too unnatural.
That is why you could figure out some uses yourself even with exceptions.
So let's hear it. Until we clear the design issues, there is not much
point in talking about coding styles and implementation.
As I see what you need is some examples of how useful this new option
will be. I am going to show some but take in account that I am
inventing those. Trying to conceive uses which you would think is
useful. And that I know I would probably fail.
I know what for I had hacked to create orphan branches myself. But
those personal experiences will not be good examples to you.
But I can foresee there will be a lot of uses even if I can not
conceive them all right now.
All said, now let's exemplify, starting with the cases I told you in
my last email:
* Do some parallel development:
Recreating the wheel: unix shell softwares.
$ vim grep.c, ...
$ git add .
$ git commit -m grep
$ git checkout -ob sed
$ vim sed.c, ...
$ git add .
$ git commit -m sed
...
* Working under unrelated parts before merging the start point of the
new software.
- You start with branch A with sources to draw math functions.
- Then you start orphan B with sources to calculate math curves, their
areas, ...
- Later you organize them and merge the start point of the new software.
- Now you are ready to publish and to call for community help.
$ vim draw.c, ...
$ git add .
$ git commit -m 'Drawing implementation'
$ git checkout -ob math
$ vim math.c, ...
$ git add .
$ git commit -m 'Complicated Math implementation'
...
* Recreate history. It is not published yet so it is not being widely
cloned and people just want to have a good repository before
publishing;
You start A--B--C--D then you realize that A and B is not necessary
and that you should have started directly by C.
$ git checkout C
$ git checkout -ob GOOD
$ git add .
$ git commit -C C --reset-author
$ git cherry-pick D
$ git branch -D OLD_BRANCH
* Adding files which is not meant to be part of anything in a temporary fashion;
Adding notes to yourself.
$ git checkout -ob notes
$ git clean -df
$ vim note
$ git add .
$ git commit -m Notes
* Have different approaches starting different sources from those
software versions until you
find out the best one.
You are going to start a software which you don't know if a good
algorithm would be to do some factorial by recursion or not.
$ vim recursive.c
$ git add .
$ git commit -m recursive
$ git checkout -ob normal
$ vim straight.c
$ git add .
$ git commit -m normal
This email is being made in chronological order. I know you have
already sent another one but I have chosen to reply this one before
seeing the new one. I will reply that one after sending this so
please forgive me if I am talking about something you later
reconsidered.
To finish this email I am going to make a 'cheat sheet' to show the
new functionality:
Branch_A
|
You realize that you need a new empty branch.
|
Is the work tree clean?
| |
Yes No
| |
git clean -ob Branch_B -------Undo?-------Was the work tree clean before?
|
| |
| Yes No
|
| |
|
| git add .
|
| git commit -m temp
|
| |
|
+--------+ git checkout Branch_A -f
|
|
|
git merge --squash Branch_B
Do you want to use anything from the work tree? |
| |
git reset
Yes No
git branch -D Branch_B
| |
| git clean -df
| |
Change the work tree the way you want it to be.
|
git add .
git commit
|
That is it!
Thank you very much for the patience to get till here. I know it is
hard reading much but I realize that all this subject have to be well
explained otherwise I will be repeating the same in a series of
emails. I have already did repeat on this one. ;-)
I hope all this effort will be worth-full. Thanks again for your time!
Regards
Hi
As I see you have found a very good example under your common work
flow. Nice. :-)
Regards
2010/3/13 Junio C Hamano [off-list ref]:
Junio C Hamano [off-list ref] writes:
quoted
As I already said, I do not think "mostly common paths" case should be
encouraged to begin with. As far as I know (and you can guess by now that
I know reasonably well about git), you do not gain anything by not having
the ancestry link between '?' and 'B', except that it would make conflict
resolution at '*' extremely difficult. There is only downside without any
upside in "mostly common paths" disjoint merge.
There is one case "mostly common paths" disjoint history can be useful.
Imagine you have a hitherto proprietary software project and want to go
open source. Perhaps your intention is to have an open source version and
an enhanced commercial version. The project contains some third-party
vendor software outside your control, and you have replaced them with open
source equivalents or disabled features that depend on them.
Your history may look like this:
o---o---A oss-base
/
---o---o---o---o master
where master is the primary version you will continue shipping to your
paying customers, with proprietary third-party components and features
that depend on them. Commits on oss-base were your work to prepare the
tree into a releasable shape, removing these proprietary stuff along with
some features.
But you cannot publish oss-base (commit A) to the public. "git log" will
show all the history that leads to it, with all the third-party stuff you
do not have license to distribute in the source form. The older parts of
the history may even have site password at customer installation you have
committed by mistake and eradicated long time ago.
If you run this three command sequence (in this message, I am assuming
that you keep the index and the working tree files intact in an updated
implementation of --orphan, which is different from the suggestion to
support "no common paths" case I mentioned in the previous message):
$ git checkout --orphan oss oss-base
$ git checkout oss-base
$ git merge -s ours oss
you will get a history of this shape:
X oss
\
o---o---A---B oss-base
/
---o---o---o---o master
with commits X, A and B all recording an identical tree. The oss branch
(commit X) is now safe to publish.
Once you have done this, further you can:
$ git checkout master
$ git merge oss-base
which gives you a history of this shape:
X oss
\
o---o---A---B oss-base
/ \
---o---o---o---o---Y master
This merge Y has to be done carefully. It inherently has to be an evil
merge because oss-base wants to replace some proprietary stuff with open
source counterparts while you may want to keep using the proprietary ones
you have support contract for in your paying customer release you will
make from the master branch. So at Y, you will most likely be reverting
some work you did on oss-base branch since it forked from master.
After setting it up, this arrangement allows you to:
- accept changes from public, and/or build changes for public, to advance
"community version" on the oss branch on top of X;
- from time to time, merge oss to oss-base;
- from time to time, merge oss-base to master.
and the histories will continue like this:
X---C---C---C---C oss
\ \
o---o---A---B-----------* oss-base
/ \ \
---o---o---o---o---Y---P---P---*---P---P master
with community commits C (either contributed from the public or you
developed yourself and gave to the community) on oss branch, with
proprietary commits P that record your own proprietary work on master
branch. Note that oss-base branch is not used to produce nor record any
commit on its own---it is merely to ease the merging from oss and master
by providing X-B link to serve as a convenient common ancestor to make
later merges easier.
Note also that it would be the most convenient if you kept both the index
and the working tree intact, if "checkout --orphan" is to be used as an
ingredient for this workflow. It _might_ actually make sense not to make
the "git checkout --orphan" an independent feature that can be randomly
abused or misused, but package the three-command sequence to create the
A-B-X open triangle above into a separate command, i.e.
$ git branch --orphan oss
would create a new branch "oss" with its own root commit X that records
the same tree as the current HEAD A, and immediately merge X back into A
to produce B, again recording the same tree, and advance the current HEAD
to point at B, like so:
X oss
\
---o---A HEAD --> ---o---A---B HEAD