How to cherry pick?

[mcarans]

I have closed my PR (https://github.com/OoliteProject/oolite/pull/564) to bring changes from 1.92-maintenance due to the strong resistance to just copying over the changes.

I would like someone to explain clearly how to cherry pick as I am unfamiliar. Linking articles is not useful. What I need is an outline of the whole process with respect to our 1.92-maintenance branch as well as a step by step example with one of the commits on 1.92-maintenance showing all the git commands required to bring that commit into master and any gotchas to look out for.

[another_commander]

I would like to know this information too. And I think it would be so much simpler if the PR was just accepted.

Standing by. @mcarans, if no information is provided in a reasonable time, please consider reopening the PR.

[hiran]

I am happy to not have experience in cherry picking.

Looking at the fact that mcarans is the only one doing changes at this time I think a merge should be considered.

However I wanted to make a point that future PRs schould have one purpose each so they are difestable for reviewers.

[Lone_Wolf]

First off : I have no personal experience with cherry-pick .

Yesterday I entered "git how to port multiple commits from one branch to another" into DDG and every result was about cherry-pick .
I do know that archlinux & mesa devs use cherry-picking so I felt mentioning it in the PR as an option was a good idea.

I am willing to spend time on figuring out how to use this and think I can create sort of a Proof of Concept by following these steps

track all commands used
Clone oolite to my workstation
Lookup the first PRs that added commits to 1.92-maintenance
git cherry-pick those commits to master
push the new version to a new sourcehut repo so others can see what has happened
post the commands used
repeat with a 2nd PR

[mcarans]

First off : I have no personal experience with cherry-pick .

Yesterday I entered "git how to port multiple commits from one branch to another" into DDG and every result was about cherry-pick .
I do know that archlinux & mesa devs use cherry-picking so I felt mentioning it in the PR as an option was a good idea.

I am willing to spend time on figuring out how to use this and think I can create sort of a Proof of Concept by following these steps

track all commands used
Clone oolite to my workstation
Lookup the first PRs that added commits to 1.92-maintenance
git cherry-pick those commits to master
push the new version to a new sourcehut repo so others can see what has happened
post the commands used
repeat with a 2nd PR

Great! As you investigate, please can you find out about the following questions (I often find that the devil is in the details):

1. Environment: Does cherry-picking need to be done on a clone of the original OoliteProject/oolite repo, or can it be done on a fork followed by a PR?
2. Target Branch: What branch do we start in: master or 1.92-maintenance?
3. Batching: Is it possible to specify a commit range, or must cherry-picking be done one commit at a time?
4. Conflict Resolution: I'm interested in how conflict resolution works. Please pick commits that touch both Obj-C .m files and shell .sh scripts. The former may give conflicts.
5. Workflow Order: For each cherry-pick (assuming more than one), what is the order?
   1. Cherry-pick 1, ..., cherry-pick N, resolve all conflicts, commit, push.
   2. Cherry-pick 1, resolve conflicts 1, ..., cherry-pick N, resolve conflicts N, commit, push.
   3. Cherry-pick 1, resolve conflicts 1, commit 1, ..., cherry-pick N, resolve conflicts N, commit N, push.
   4. Some other order.
6. Verification: What do we expect to see in the commit history at the end of the process so we know it has been done correctly?

[hiran]

How about running a PR not for the master branch but a new one instead? With that the commits are 'saved' where we all have access to.

Then we can create another branch based on master. Here is where we collect the cherries from the branch that hosts all the commits.

Git Cherry-pick
The first command in this series is called git cherry-pick. It takes on the following form:

Code: Select all

git cherry-pick <Commit1> <Commit2> <...>

It’s a very straightforward way of saying that you would like to copy a series of commits below your current location (HEAD). I personally love cherry-pick because there is very little magic involved and it's easy to understand.

If need be, that website https://learngitbranching.js.org has helped me understand git with easy explanations and good visualization.

Once we collected the commits necessary for one meaningful change we run a PR to merge into master.
Then the game repeats until we are satisfied.

To know whether we are satisfied we can compare branches using git diff. That one is also explained in the above site and boils down to

Code: Select all

git diff branch1 branch2

If only one branch is given the diff will run vs the current files on disk.

[phkb]

FWIW, it would actually be faster to cherry pick all the changes on master to the 1.92_maintenance branch, as it's 42 commits ahead, but only 19 commits behind.

[Lone_Wolf]

@hiran & @phkb :
wouldn't that require changing the default branch ?

Great! As you investigate, please can you find out about the following questions (I often find that the devil is in the details):

I'm currently reading up on git-cherry-pick and git-merge manpages and can give partial answers already .

• 1. porting to a new branch is possible (and my intention). How forking works is a bit of a black box to me.
  I'd prefer to have everything worked out in a separate branch before looking at forking/creating a PR.
• 2. since master is default branch (and I don't see why we should change default branch) porting 1.92.maintenance commits to master seems the logical choice.
• 3. batching : multiple commits and ranges can be used
• 4. there are options to ignore white space, this should help a lot.
• 5. I personally prefer to combine multiple commits in a push to make reverting to a clean state simple and keep simple mistakes/errors from cluttering git log.
• 6.

  -x
  When recording the commit, append a line that says "(cherry picked from commit ...)" to the original commit message in order to indicate which commit this change was cherry-picked from. This is done only for cherry picks without conflicts. Do not use this option if you are cherry-picking from your private branch because the information is useless to the recipient. If on the other hand you are cherry-picking between two publicly visible branches (e.g. backporting a fix to a maintenance branch for an older release from a development branch), adding this information can be useful.

  That options look very useful for this.

[hiran]

Branches are just labels attached to a commit. If you create a new commit on a branch's head the branch label will be moved to the new commit. Branch labels can be created and deleted, but tgey can be moved around to point to other commits also.

The solution I proposed would start on master and add the cherries from the release branch. I'd do so on a separate branch but all these operations - apart from cherry picking - are our business as usual.

The solution proposed by phkb would look at it from the other side: start on the release branch and add the cherries from master. Again I'd do so on a separate branch, but in the end we would just move the master label to the head of that separate branch. Before moving master create a branch label where master was in case we want to go back.

As phkb pointed out there would be less cherries to be picked and moving the branch labels is no big effort.

If in doubt have a look at learngitbranching. It explains and visualizes very well.

[mcarans]

Another approach would be to do a merge of 1.92-maintenance into master fixing any merge conflicts ie:
https://github.com/OoliteProject/oolite ... aintenance

I think it likely that most of the conflicts would be resolved by accepting the changes from 1.92-maintenance.

[hiran]

How about creating a new branch from master and merging the release branch? We can have a look at the result before merging into master.

[mcarans]

How about creating a new branch from master and merging the release branch? We can have a look at the result before merging into master.

I was thinking of something similar in a fork. I was wondering how it would work and ensure the git history looks ok and asked AI which said:

If you want to keep the original maintainers happy and ensure the log looks professional, follow this workflow:

Sync your fork: Ensure your master is up to date with the original repo.

Merge via command line: ```bash
git checkout master
git merge 1.92-maintenance --no-ff

*(The `--no-ff` flag ensures a merge commit is created even if it could have been a fast-forward, which clearly marks the version integration in the log.)*

Push and PR: When you open the PR, tell the maintainers: "This merges the 1.92-maintenance improvements into master. Please use a standard merge commit (no squash) to preserve the maintenance history."

[hiran]

I am ok with all but that final PR from your fork to oolite master.

Why would have it go to that branch? Pick/create a new one so it is in the oolite repo and visible to everyone and gets processed by the CI/CD chain. If good we can still run a PR to merge into master. Or cherry pick. Or ....

[Lone_Wolf]

Merging the first differing commit will fail as that updates the version from 1.92 to 1.92.1 and master is at 1.93
The change in the 2nd commit is already present in master.
Both will have to be skipped and documented why they are skipped.

git cherry-pick does use git merge but is a lot more flexible .

EDIT1

My preparations are ready now and can be followed at https://git.sr.ht/~lone_wolf/oolite-tes ... herry-pick

EDIT2
It seems preparation was wrong, as 1.92-maintenance is not part of the new repo or listed in the remotes.
Will look into it tomorrow.

[mcarans]

Merging the first differing commit will fail as that updates the version from 1.92 to 1.92.1 and master is at 1.93
The change in the 2nd commit is already present in master.
Both will have to be skipped and documented why they are skipped.

What purpose does documenting those two examples serve? In the first case, it is obvious why master should retain 1.93 not use 1.92 or 1.92.1. In the second case, surely the point is to document things that are being changed not things that are staying the same?

I don't think I've seen a project where people give commit by commit descriptions of what is merged from one branch into another: people generally highlight the salient changes so that future developers can tell the wood from the trees. Then if developers want to know more, they delve into the code changes in the PR.

I asked AI which said:

When moving changes from a maintenance branch like 1.92-maintenance back into master, merging is almost always the better choice.

Why Merging is Better (Maintenance → Master)

Preserved Lineage: Merging tells Git (and other developers) that these two branches have "synced up." If you cherry-pick, Git doesn't realize the code is now in both places. The next time you try to merge, Git might show you the same conflicts all over again because it thinks the changes are different.

Conflict Resolution: If you have 10 bug fixes in 1.92-maintenance, a merge allows you to resolve all conflicts in one single session. If you cherry-pick, you have to resolve them 10 times, once for each commit.

No Duplicate Commits: Merging keeps the original commit hashes. Cherry-picking creates "ghost" copies of the commits with new hashes, which can make the git log harder to audit later.

Code: Select all

Feature		Merging 1.92 into master		Cherry-picking into master
Effort		Low (Resolve conflicts once		High (Resolve conflicts per commit)
Traceability	High (Clear link between branches)	Low (Disconnected duplicate commits)
Risk		Minimal					Risk of "double-applying" code later

Basically it said that cherry picking could be used for backporting fixes from master into 1.92-maintenance while merging is for forward porting fixes from 1.92-maintenance to master.