On Tue, Sep 30, 2008 at 6:05 PM, Thomas Rast <trast@xxxxxxxxxxxxxxx> wrote: > As a quick status update, mostly to show that I haven't forgotten > about this topic: > > Thanks Santi and Dmitry for your comments. You have raised some very > good points, and I attempted to fix these issues. Thanks for you document. > > Unfortunately, in some places I got stuck trying to work out good > explanations for the workings of git.git, and some of the newer > rearrangements left the lead of "Merging branches" in a dire state. > I'll see if I can find a good solution myself, but suggestions would > be welcome in any case. The WIP text is below, and I'll follow up > with an interdiff to the last version. > > - Thomas > [...] > > SEPARATE CHANGES > ---------------- > > As a general rule, you should try to split your changes into small > logical steps, and commit each of them. They should be consistent, > working independently of any later commits, pass the test suite, etc. > This makes the review process much easier, and the history much more > useful for later inspection and analysis, for example with > linkgit:git-blame[1] and linkgit:git-bisect[1]. > > To achieve this, try to split your work into small steps from the very > beginning. It is always easier to squash a few commits together than > to split one big commit into several. Don't be afraid of making too > small or imperfect steps along the way. You can always go back later > and edit the commits with `git rebase \--interactive` before you > publish them. > I know it is against the recommendation but I think it makes sense to explain how you can split big patches testing them as is explained in gitlink:git-stash. [...] > Graduation > ~~~~~~~~~~ > > As a given feature goes from experimental to stable, it also > "graduates" between the corresponding branches of the software. > `git.git` uses the following 'main branches': > > * 'master' tracks the commits that should go into the next release; > > * 'maint' tracks the commits that should go into the next "maintenance > release", i.e., update of the last released stable version; and The "logical" order would be 'maint', 'master', 'next', 'pu', each one should fast-forward to the next one. > > * 'next' is intended as a testing branch for people who like to use > more experimental stuff. The key point is not "more experimental stuff", but 'master' material but not stable enough. [...] > Integration branches > ~~~~~~~~~~~~~~~~~~~~ > > If you followed the last paragraph, you will now have many small topic > branches, and occasionally wonder how they interact. Perhaps the > result of merging them does not even work? But on the other hand, we > want to avoid merging them anywhere "stable" because such merges > cannot easily be undone. > > The solution, of course, is to make a merge that we can undo: merge > into a throw-away branch. > > .Integration branches > [caption="Rule: "] > ===================================== > To test the interaction of several topics, merge them into a > throw-away branch. > ===================================== > > If you make it (very) clear that this branch is going to be deleted > right after the testing, you can even publish this branch, for example > to give the testers a chance to work with it, or other developers a > chance to see if their in-progress work will be compatible. `git.git` > has such an official integration branch called 'pu'. You must never > base any work on such a throw-away branch! Maybe this last sentence should go in the "Rule:". > > > SHARING WORK > ------------ > > After the last section, you should know how to manage topics. In > general, you will not be the only person working on the project, so > you will have to share your work. Sharing work is explained in the tutorials, maybe this section should be about "distributed workflows". > > Roughly speaking, there are two important workflows: push/pull and > format-patch/am. A more descriptive name could be the "merge workflow" and the "patch workflow". > The important difference is that push/pull can > propagate merges, while format-patch cannot. Like I said in the other mail, the key is that one preserves the history (including merges) and the other not. This is what makes possible the push/pull workflow, that all the branches should fast-forward (and this should be said somewhere) > Medium to large projects > will typically employ some mixture of the two: s/:/./ Although I think it should be deleted. And what about litle projects? Different roles do uses different workflows: > > * "Upstream" in the most general sense 'pushes' changes to the > repositor(ies) holding the official history of the project. > Everyone can 'fetch' from there to stay up to date. s/pushes/publishes/ s/fetch/merge/ > > * Frequent contributors, subsystem maintainers, etc. may push to a > public repository to make their changes available to upstream. s/push/publish/ Or: * Frequent contributors, subsystem maintainers, etc. may publish to a public repository to make their changes available to upstream, or to their downstreams (acting as upstream to them) > > * The rest -- typically anyone more than one or two levels away from the > main maintainer -- send patches by mail. In the "distributed workflows" this would be: * "Upstream" merges the branches from subsystem maintainers, applies the 'patches' from others (including themselves) and publishes to the main repository. See link:howto/maintain-git.txt to see how it is done in git.git) * "Subsystem maintainers" act as "upstream" but publishes to a different repository/branch. * Frequent contributors, etc, publish their changes in another repository. * The rest ... > > None of these boundaries are sharp, so find out what works best for > you. > > > Push/pull > ~~~~~~~~~ > > There are three main tools that can be used for this: Sorry, but I don't see the point explaining how to publish the branches, or keep them up to date. > > If you are a maintainer and would like to merge other people's topic > branches to the main branches, they will typically send a request to > do so by mail. Such a request might say > > ------------------------------------- > Please pull from > git://some.server.somewhere/random/repo.git mytopic > ------------------------------------- > > In that case, 'git-pull' can do the fetch and merge in one go, as > follows. Or: Then, you can merge them with just: > .Push/pull: Merging remote topics > [caption="Recipe: "] > ===================================== > `git pull <url> <branch>` > ===================================== > Use "<url> <branch>" or "git://some.server.somewhere/random/repo.git mytopic" in the recipies, but not both. [...] > > format-patch/am > ~~~~~~~~~~~~~~~ s/.*/patch workflow/ > > If you are a contributor that sends changes upstream in the form of > emails, you should use topic branches as usual (see above). Then use > linkgit:git-format-patch[1] to generate the corresponding emails > (highly recommended over manually formatting them because it makes the > maintainer's life easier). > > .format-patch/am: Publishing branches/topics > [caption="Recipe: "] > ===================================== > * `git format-patch -M upstream..topic` to turn them into preformatted > patch files > * `git send-email --to=<recipient> <patches>` > ===================================== > > See the linkgit:git-format-patch[1] and linkgit:git-send-email[1] > manpages for further usage notes. Also you should be aware that the > maintainer may impose further restrictions, such as "Signed-off-by" > requirements. The restrictions and the Signed-off-by also applies to the other workflows. > > If the maintainer tells you that your patch no longer applies to the > current upstream, you will have to rebase your topic (you cannot use a > merge because you cannot format-patch merges): > > .format-patch/am: Keeping topics up to date > [caption="Recipe: "] > ===================================== > `git pull --rebase <url> <branch>` > ===================================== > > You can then fix the conflicts during the rebase. Presumably you have > not published your topic other than by mail, so rebasing it is not a > problem. > > If you receive such a patch (as maintainer, or perhaps as a reader of > the mailing list it was sent to), save the mail to a file and use > 'git-am': > > .format-patch/am: Publishing branches/topics > [caption="Recipe: "] > ===================================== > `git am < patch` > ===================================== > > One feature worth pointing out is the three-way merge, which can help > if you get conflicts: `git am -3` will use index information contained > in patches to figure out the merge base. See linkgit:git-am[1] for > other options. > > > SEE ALSO > -------- > linkgit:gittutorial[7], > linkgit:git-push[1], > linkgit:git-pull[1], > linkgit:git-merge[1], > linkgit:git-rebase[1], > linkgit:git-format-patch[1], > linkgit:git-send-email[1], > linkgit:git-am[1] > > GIT > --- > Part of the linkgit:git[1] suite. > > > -- 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
