Cherry-pick several commits on a branch using the low level Git Data operations provided by the GitHub REST API
npm install github-cherry-pick 
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.
``javascript
import { cherryPickCommits } from "github-cherry-pick";
const example = async () => {
const newHeadSha = await cherryPickCommits({
// The SHA list of the commits to cherry-pick.
// The commits will be cherry-picked in the order they appear in the array.
// Merge commits are not supported.
// See https://git-scm.com/docs/git-cherry-pick for more details.
commits: [
"8b10a7808f06970232dc1b45a77b47d63641c4f1",
"f393441512c54435819d1cdd8921c0d566911af3",
],
// The name of the branch/reference on top of which the commits will be cherry-picked.
head: "awesome-feature",
// An already authenticated instance of https://www.npmjs.com/package/@octokit/rest.
octokit,
// The username of the repository owner.
owner,
// The name of the repository.
repo,
});
};
`
github-cherry-pick can run on Node.js and in recent browsers.
github-cherry-pick uses debug to log helpful information at different steps of the cherry-picking process.DEBUG
To enable these logs, set the environment variable to github-cherry-pick.
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!
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:
1. Create a temp branch from master with POST /repos/:owner/:repo/git/refs.`
`
* 4620c9b (feature) E
* 317c828 D
* 7599421 C
| * 00ad8d7 (HEAD -> temp, master) B
|/
* 72cc07d A
00ad8d7
2. Create a commit from the tree of with 7599421 as parent with POST /repos/:owner/:repo/git/commits and update temp'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
317c828
3. Merge on temp 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
55a7299
4. Create another commit from with 00ad8d7 as the only parent and update temp's reference to point to this new commit.`
`
* 3698031 (HEAD -> temp) D
* 00ad8d7 (master) B
| * 4620c9b (feature) E
| * 317c828 D
| * 7599421 C
|/
* 72cc07d A
4620c9b
5. Repeat steps 2. and 3. to cherry-pick on temp.`
`
* d82c247 (HEAD -> temp) E
* 3698031 D
* 00ad8d7 (master) B
| * 4620c9b (feature) E
| * 317c828 D
| * 7599421 C
|/
* 72cc07d A
master
6. Set 's reference to the same as temp 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
temp
7. Delete the 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
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.