Repository files navigation

github-cherry-pick cherry-picks several commits on a branch usingthe low level Git Data operations provided by the GitHub REST API.

It's the building block ofgithub-backport andgithub-rebase.

This library was developed to makeAutorebase possible but focus has shifted to the development of its successor:Autosquash.

This project will thus stop receiving updates.

import{cherryPickCommits}from"github-cherry-pick";constexample=async()=>{constnewHeadSha=awaitcherryPickCommits({// 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 usesdebug to log helpful information at different steps of the cherry-picking process.To enable these logs, set theDEBUG environment variable togithub-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-pick317c828 and4620c9b on themaster branch.

github-cherry-pick would then take the following steps:

1. Create atemp branch frommaster withPOST /repos/:owner/:repo/git/refs.

   * 4620c9b (feature) E* 317c828 D* 7599421 C| * 00ad8d7 (HEAD -> temp, master) B|/* 72cc07d A

2. Create a commit from the tree of00ad8d7 with7599421 as parent withPOST /repos/:owner/:repo/git/commits and updatetemp's reference to point to this new commit withPATCH /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

3. Merge317c828 ontemp withPOST /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

4. Create another commit from55a7299 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

5. Repeat steps 2. and 3. to cherry-pick4620c9b ontemp.

   * d82c247 (HEAD -> temp) E* 3698031 D* 00ad8d7 (master) B| * 4620c9b (feature) E| * 317c828 D| * 7599421 C|/* 72cc07d A

6. Setmaster's reference to the same astemp withPATCH /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

7. Delete thetemp branch withDELETE /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 aretests for it.