Goal
github-cherry-pick
cherry-picks several commits on a branch using the low level Git Data operations provided by the GitHub REST API.
It's the building block of github-backport
and github-rebase
.
Usage
; const example = async { const newHeadSha = await ;};
github-cherry-pick
can run on Node.js and in recent browsers.
Troubleshooting
github-cherry-pick
uses debug
to log helpful information at different steps of the cherry-picking process.
To enable these logs, set the DEBUG
environment variable to github-cherry-pick
.
How it Works
The GitHub REST API doesn't provide a direct endpoint for cherry-picking commits on a branch but it does provide lower level Git operations such as:
- merging one branch on top of another one
- creating a commit from a Git tree
- creating/updating/deleting references
It turns out that's all we need to perform a cherry-pick!
Step by Step
Let's say we have this Git state:
* 4620c9b (feature) E
* 317c828 D
* 7599421 C
| * 00ad8d7 (HEAD -> master) B
|/
* 72cc07d A
and we want to cherry-pick 317c828
and 4620c9b
on the master
branch.
github-cherry-pick
would then take the following steps:
- Create a
temp
branch frommaster
with POST /repos/:owner/:repo/git/refs.* 4620c9b (feature) E * 317c828 D * 7599421 C | * 00ad8d7 (HEAD -> temp, master) B |/ * 72cc07d A
- Create a commit from the tree of
00ad8d7
with7599421
as parent with POST /repos/:owner/:repo/git/commits and updatetemp
's reference to point to this new commit with PATCH /repos/:owner/:repo/git/refs/:ref.* 80c410e (HEAD -> temp) Use tree of 00ad8d7 | * 4620c9b (feature) E | * 317c828 D |/ * 7599421 C | * 00ad8d7 (master) B |/ * 72cc07d A
- Merge
317c828
ontemp
with POST /repos/:owner/:repo/merges.* 55a7299 (HEAD -> temp) Merge commit '317c828' into temp |\ * | 80c410e Tree of 00ad8d7 with 7599421 as parent | | * 4620c9b (feature) E | |/ | * 317c828 D |/ * 7599421 C | * 00ad8d7 (master) B |/ * 72cc07d A
- Create another commit from
55a7299
with00ad8d7
as the only parent and updatetemp
's reference to point to this new commit.* 3698031 (HEAD -> temp) D * 00ad8d7 (master) B | * 4620c9b (feature) E | * 317c828 D | * 7599421 C |/ * 72cc07d A
- Repeat steps 2. and 3. to cherry-pick
4620c9b
ontemp
.* d82c247 (HEAD -> temp) E * 3698031 D * 00ad8d7 (master) B | * 4620c9b (feature) E | * 317c828 D | * 7599421 C |/ * 72cc07d A
- Set
master
's reference to the same astemp
with PATCH /repos/:owner/:repo/git/refs/:ref, making sure it's a fast-forward update.* d82c247 (HEAD -> master, temp) E * 3698031 D * 00ad8d7 B | * 4620c9b (feature) E | * 317c828 D | * 7599421 C |/ * 72cc07d A
- Delete the
temp
branch with DELETE /repos/:owner/:repo/git/refs/:ref and we're done!* d82c247 (HEAD -> master) E * 3698031 D * 00ad8d7 B | * 4620c9b (feature) E | * 317c828 D | * 7599421 C |/ * 72cc07d A
Atomicity
github-cherry-pick
is atomic.
It will either successfully cherry-pick all the given commits on the specified branch or let the branch untouched if one commit could not be cherry picked or if the branch reference changed while the cherry-picking was happening.
There are tests for it.