Git: determining up / down directions between branches seems contradictory

Question

I read the gitworkflows documentation at https://git-scm.com/docs/gitworkflows (also read in man gitworkflows), but determining the up / down directions between branches feel illogical to me. I did not understand the meaning, so I wonder if there is something that I do not see.

In particular, the "Branch Management> Ending" section in the above documentation contains

Release

Since this feature goes from experimental to sustainable, it is also a "graduate" between the respective software branches. git.git uses the following integration branches:

• maint keeps track of commits that should go to the next "maintenance" release, that is, updating the latest released stable version;

• the wizard tracks the commits that should go to the next version;

• next is intended as a testing branch for topics tested for stability for the wizard.

There is a fourth official branch that is used somewhat differently:

• pu (proposed updates) is an integration branch for things that are not completely ready for inclusion (see the section "Integration branches" below).

Each of the four branches is usually a direct descendant above it.

The last sentence seems to imply that maint> master> next> pu is a downstream direction (because master is a descendant of maint, etc.).

However, the documentation further states

Conceptually, this function enters an unstable branch (usually the next or pu), and "graduates" to master the next version when it is considered stable enough.

Merge up

"graduation down", considered above [...]

Thus, in the last sentence, the documentation actually defines the distribution of new functions in the direction of the next> master as "grading down." This is the opposite of my previous impression that the master> next is a downward direction.

For me, the definition of maint> master> next> pu as a downward direction feels not only more natural, but also more consistent with the definition of upstream / downstream repositories. Usually we clone the remote upstream repository into the local repository, implement new features, and push up to the remote repository. (Note that the last step here is called “push up.”) This general procedure is parallel to branching next to the master, implements new functions in the next, and combines them into a master. Therefore, I think that the distribution of new features next to the wizard should be called "upward gradation" (in parallel with the "push up" from the local to the remote repository). However, it is called "down grading" in the documentation.

Why does Git use this inconsistent definition of up / down directions between branches? How can I understand that? Or, is there something important that I am missing to understand this definition?

Answer 1

Since 2009, all of these down / up mergers have been automated using the Reintegrate script used by Junio ​​C. Hamano (explained in commit cc1b258 ) for managing git branches from gitster/git (which has many branches)

But back in 2007, the first revision of Documentation/howto/maintain-git.txt was more explicit (and manual)

I think the distribution of new functions from next to master should be called "upward gradation"

I agree, the original file showed :

Merge down if necessary ( master->next ):

  $ git checkout next $ git merge master $ make test 

In this case, if you combine next into master (to complete the next release into a new git release in master ), you merge up.

There was an interesting discussion around the more modern form Documentation/gitworkflows.txt presented in 2008 by Thomas Rast ( trast )

Junio ​​C. Hamano is mentioned there:

This description skips the most important reason why merging with the topic of a branch is not a good idea. As soon as you combine the integration of a general purpose branch, such as master , into a topic branch, the branch ceases to be the only topic.
It becomes: "The theme and other unrelated changes are mixed."

Always merging upwards is a good rule, and when used with a branch theme, there is one twist that you did not mention, but you should know about.
A topic intended for the final transition to an older integration branch (for example, maint ) does not have to be combined with its final destination branch in the first place.
I often do this:

  git checkout tr/maint-fix-bla maint git am -s fix-mail-from-thomas.txt git checkout next git merge tr/maint-fix-bla ... cook further, perhaps adding more commits to ... tr/maint-fix-bla topic and merging the result to next; ... and then when the topic appears to be stable do: git checkout master git merge tr/maint-fix-bla vvvvvvvvvvvvvvvvvvvvvvvvv ... and later git checkout maint git merge tr/maint-fix-bla git branch -d tr/maint-fix-bla 

This prevents obsolescence of old integration branches until the topic gets proven that they have no regression in the field.
This workflow is safer and more suitable for the final branch of integration, to which the known gender is better than unintentional regression.

An alternative would be for the reader to assume from your description of a merge up that would look like this:

  git checkout tr/maint-fix-bla maint git am -s fix-mail-from-thomas.txt git checkout maint git merge tr/maint-fix-bla git checkout master git merge maint git checkout next git merge master 

This can inadvertently regress the maint , and then the regression propagates upward to pollute all integration branches.

WITH

we use the word "integration branches" to refer to persistent branches such as maint / master / next .