LinuxCommandLibrary

git-cherry

Find commits not yet up-streamed

TLDR

Show commits (and their messages) with equivalent commits upstream

$ git cherry [[-v|--verbose]]
copy

Specify a different upstream and topic branch
$ git cherry [origin] [topic]
copy

Limit commits to those within a given limit
$ git cherry [origin] [topic] [base]
copy

SYNOPSIS

git cherry [-v] [ [ []]]

PARAMETERS

-v
    Enables verbose output, showing the full SHA-1 of the commits in addition to the status prefix.

<upstream>
    The commit (or branch/tag reference) that limits the set of commits considered "applied." Commits in <head> are checked against this range. Defaults to FETCH_HEAD if not specified.

<head>
    The commit (or branch/tag reference) that defines the set of commits to be checked for application in <upstream>. Defaults to HEAD if not specified.

DESCRIPTION

The git-cherry command is used to identify commits that exist on one branch but have not yet been applied (either directly or via cherry-pick) to another specified upstream branch. It compares two commit ranges: one representing the "upstream" branch and another representing the "head" branch. Its primary use case is for project maintainers or developers who want to track which patches from a feature branch or fork have been integrated into the main development line.

git-cherry works by computing a "patch ID" for each commit in the <head> range and then checking if a commit with an identical patch ID exists in the <upstream> range. Commits with matching patch IDs are considered "applied," even if their SHA-1 hashes differ due to rebase or cherry-picking. Commits without a match are reported as "missing." It helps determine what work still needs to be pulled upstream or what commits have been successfully integrated.

CAVEATS

git-cherry is an approximation and might produce false positives. It explicitly does not take merge commits into account when comparing commit ranges. If a commit from <head> was integrated into <upstream> via a merge commit rather than a cherry-pick or direct application, git-cherry might report it as "missing."
The <limit> argument in the synopsis is deprecated and has no effect.

<B>OUTPUT</B>

The output of git cherry consists of a list of commits, each prefixed with a status character:
+ (plus sign): Indicates that the commit from the <head> branch appears to be not applied to the <upstream> branch.
- (minus sign): Indicates that the commit from the <head> branch has been applied to the <upstream> branch.
Following the prefix, the commit subject line is displayed. If the -v option is used, the full SHA-1 of the commit is also shown before the subject line.

HISTORY

The git-cherry command has been a part of Git since its early days, designed to help developers and maintainers track the integration status of commits. Its purpose aligns with Git's distributed nature, enabling clearer communication and management of patches flowing between different repositories or branches. It specifically leverages the git-patch-id mechanism, which was introduced to provide a stable identifier for a patch's content, regardless of its commit SHA-1, making git-cherry resilient to rebases and cherry-picks.

SEE ALSO

Copied to clipboard