🍒 Cherri

Cherry-pick PRs with ease! Automatically cherry-pick merged pull requests marked with a specific emoji in their title or with a specific label.

About the Name

Why Cherri? It's a blend of "cherry-pick" and the French "chérie" (sweetheart), because let's face it - some commits are just more loveable than others. When you mark a PR with that little cherry emoji, you're essentially saying "this one's my chérie" - it's the commit equivalent of a love letter that deserves to be cherry-picked and brought along to every important branch.

What is Cherri?

Cherri is a CLI tool that automates the process of cherry-picking commits from merged pull requests. It searches for PRs with a specific emoji (default: 🍒) in their title OR PRs with a specific label, and cherry-picks all commits from those PRs to your current branch.

Perfect for:

• Backporting features to release branches
• Maintaining LTS versions
• Selective feature deployment
• Managing hotfixes across multiple branches

Installation

Install Cherri globally using npm:

npm install -g cherri

Prerequisites

• Node.js (v16 or higher)
• Git installed and configured
• GitHub Personal Access Token with repo access
• You must be in the target git repository when running the command

Setup

1. GitHub Personal Access Token

1. Create a GitHub Personal Access Token:

   • Go to GitHub Settings → Developer settings → Personal access tokens
   • Generate a new token with repo scope
   • Copy the token

2. Set the environment variable:

   export GITHUB_TOKEN="your_github_token_here"
   

   Or add it to your .bashrc/.zshrc:

   echo 'export GITHUB_TOKEN="your_github_token_here"' >> ~/.bashrc
   

2. Git Merge Tool Configuration

Before running Cherri, please set up your merge tool for automatic conflict resolution. When conflicts occur during cherry-picking, they will be handled one by one, opening your configured editor for each conflicted file individually.

Add one of these configurations to your global ~/.gitconfig file:

For Cursor:

[merge]
    tool = cursor
[mergetool "cursor"]
    cmd = cursor --reuse-window --wait $MERGED

For VS Code:

[merge]
    tool = vscode
[mergetool "vscode"]
    cmd = code --wait $MERGED

For other popular editors:

# For Vim 🗿
[merge]
    tool = vimdiff

# For Emacs 🤓 ( only tsoding 🗿 uses this lol )
[merge]
    tool = emerge

After adding this configuration, git will automatically open your editor when conflicts need to be resolved during cherry-picking.

Project Configuration

Instead of specifying repository details via command-line flags each time, you can create a cherri.json configuration file in your project root to define reusable profiles.

Configuration File Structure

Create a cherri.json file in your project root:

{
  "profiles": [
    {
      "name": "main",
      "configuration": {
        "owner": "your-org",
        "repo": "your-repo",
        "emoji": "🍒",
        "label": "cherry-pick",
        "prTitle": "Custom Release PR Title",
        "prBodyTemplate": "## 🚀 Release Backport\n\nBackporting {{prCount}} PRs to {{targetBranch}}:\n\n{{prList}}\n\n### Stats\n- Commits: {{commitCount}}\n- Date: {{date}}"
      }
    },
    {
      "name": "staging",
      "configuration": {
        "owner": "your-org", 
        "repo": "your-repo",
        "emoji": "🚀",
        "label": "hotfix"
      }
    }
  ]
}

Using Profiles

Use the -p or --profile flag to specify which profile to use:

# Use the "main" profile configuration
cherri -p main

# Use the "staging" profile configuration  
cherri -p staging

# You can still override specific options when using a profile
cherri -p main --interactive --since 2

Configuration Options

Each profile's configuration object supports:

| Field | Description | Required | Default | |-------|-------------|----------|---------| | owner | GitHub repository owner | Yes | - | | repo | GitHub repository name | Yes | - | | emoji | Emoji to search for in PR titles | No | 🍒 | | label | Search for PRs with this label | No | - | | prTitle | Custom title for the created PR (only used with --create-pr) | No | Cherri: X PR(s) (Y selected) | | prBodyTemplate | Custom template for PR body with variable substitution (only used with --create-pr) | No | Default format |

Notes:

• When using -p, you cannot specify --owner or --repo flags (they come from the profile)
• Other command-line options can still be used and will override profile settings
• The configuration file is searched in the current directory and parent directories up to the git root

Usage

Basic Command

cherri -o <owner> -r <repo>

Using Configuration File

cherri -p <profile-name>

Options

| Option | Alias | Description | Required | Default | |--------|-------|-------------|----------|---------| | --profile | -p | Profile name from cherri.json configuration file | No | - | | --owner | -o | GitHub repository owner | Yes* | - | | --repo | -r | GitHub repository name | Yes* | - | | --since | -s | Time period to look back for PRs (e.g., '1w3d4h', '7d', '2' for 2 months) | No | 1 | | --since-branch | - | Use branch creation date as cutoff (e.g., 'main', 'release/v1.0') - alternative to --since | No | - | | --emoji | -e | Custom emoji to search for in PR titles and display in logo | No | 🍒 | | --interactive | -i | Enable interactive mode for PR selection | No | false | | --select-commits | - | Interactively select individual commits from each PR (requires -i) | No | false | | --source-branch | -b | Source branch, defaults to the default branch | No | Auto-detected | | --label | -l | Search for PRs with this exact label (replaces title search) | No | - | | --fail-on-conflict | - | Exit with error when conflicts are detected instead of prompting for resolution | No | false | | --create-pr | - | Create a PR instead of direct cherry-picking. Optionally specify target branch (defaults to source branch) | No | false |

* Required unless using --profile with a configuration file

Note: Use either --since OR --since-branch, not both. They serve the same purpose but use different methods to determine the cutoff date for PRs.

Examples

Basic usage - search for PRs with 🍒 in title

cherri -o facebook -r react

Look back 3 months for PRs

cherri -o microsoft -r vscode -s 3

Look back 1 week and 2 days for PRs

cherri -o microsoft -r vscode -s 1w2d

Look back 7 days for PRs

cherri -o microsoft -r vscode -s 7d

Look back 2 hours for PRs

cherri -o microsoft -r vscode -s 2h

Alternative: Use branch creation date as cutoff

# Use either --since OR --since-branch, not both
cherri -o your-org -r your-repo --since-branch main

Get all PRs since a release branch was created

cherri -o your-org -r your-repo --since-branch release/v2.0

Use a custom emoji marker

cherri -o your-org -r your-repo -e "🚀"

Interactive mode - manually select PRs

cherri -o microsoft -r vscode -i

Interactive commit selection - select specific commits from each PR

cherri -o your-org -r your-repo -i --select-commits

Specify custom source branch

cherri -o your-org -r your-repo -b release/1.0

Search by exact label only (replaces title search)

cherri -o your-org -r your-repo -l "cherry-pick"

Fail on conflict instead of prompting for resolution

cherri -o your-org -r your-repo --fail-on-conflict

Create PR instead of direct cherry-picking

cherri -o your-org -r your-repo --create-pr

Create PR targeting a specific branch

cherri -o your-org -r your-repo --create-pr release/v1.0

Create PR with specific time period

cherri -o your-org -r your-repo -s 1w --create-pr

Combine all options

cherri -o facebook -r react -s 2 -i -b main -l "hotfix" --fail-on-conflict

Time Period Formats

The --since flag supports flexible time period specifications. Alternatively, you can use --since-branch to use a branch's creation date as the cutoff.

Supported Units

• w = weeks
• d = days
• h = hours
• m = minutes

Examples

# Complex combinations
cherri -s 1w3d4h    # 1 week, 3 days, 4 hours ago
cherri -s 2d12h     # 2 days, 12 hours ago
cherri -s 30m       # 30 minutes ago

# Individual units
cherri -s 7d        # 7 days ago
cherri -s 2h        # 2 hours ago
cherri -s 45m       # 45 minutes ago

# Backward compatible (bare numbers = months)
cherri -s 2         # 2 months ago (same as before)
cherri -s 1         # 1 month ago (default)

# Alternative: Branch-based cutoff
cherri --since-branch main        # Since main branch was created
cherri --since-branch release/v1.0  # Since release branch was created

Notes

• Backward Compatible: Bare numbers without units still work as months
• Flexible: Mix and match any combination of time units
• Precise: Calculations use milliseconds for accuracy
• Alternative: Use --since-branch for branch-based cutoffs instead of time calculations

PR Creation Mode

When using the --create-pr flag, Cherri will create a pull request instead of directly cherry-picking commits. This is useful for review workflows where changes need approval before merging.

How it works:

1. Branch Creation: Creates a new branch with format cherri/auto-{timestamp}
2. Cherry-picking: Applies all selected commits to the new branch
3. PR Creation: Creates a pull request from the new branch to your target branch
4. Cleanup: Switches back to your original branch

Example workflow:

# Create PR