Are you baffled by backports? Confused by cherry-picks? Muddled by merges? Branch Detective is the easy way to see what commits are present in one branch and absent from the other.
To use, just run branch-detective from the Git repository you're
examining, and pass the two branches you're comparing. The first branch is
the source branch, where commits are coming from. The second branch
is the destination branch, which you're search through for the commits in.
If a commit is present in source, but not in destination, that commit is
considered "missing".
If you don't specify the source, the current branch will be used, and if you don't
specify the destination, the local copy of the default branch (e.g. main) will be
used. Thus, branch-detective without any arguments will display the commits present
in the current branch, but absent from main.
To keep things simple, Branch Detective will not tell you about commits present in the destination branch, but not in the source branch. To see these, rerun Branch Detective with the branches swapped.
You can output the list of commits in Markdown format, for copying and pasting
as your Pull Request/Merge Request description. Just pass the --markdown
or -m option.
If all your commits consist either of a single line or have a blank line between
the header line and the body of the commit, then the first line will be formatted
as a heading 2 (## like this). If your commits don't follow this structure,
horizontal rules with dashes will be used to separate commits instead (-----).
Different Git platforms handle your repository in different ways. In some, it is possible to directly compare the unique SHAs of commits in different branches. However, in many cases, these SHAs are changed through merges, cherry-picks, rebases, and other history-altering changes.
By default, Branch Detective uses the commit message to determine if two commits are identical. It also knows how to ignore "cherry pick" footers to minimize false positives for missing commits.
If you prefer, you can pass the argument --by-sha to compare by
commit SHA instead. This will check for commits in the destination
branch that match the SHA either directly or via the cherry pick footer.
Thus, if commit a1b2c3 is cherry-picked from the source branch into
the destination branch, while it will actually have a different SHA, it will
be considered a match by Branch Detective, since the cherry pick footer will
contain the source SHA a1b2c3.
If your Git platform generates merge commits in addition to the regular commits themselves, Branch Detective allows you to ignore merge commits altogether. This cuts through the muck of the merge process and shows you only those missing commits that actually contain real code changes.
By default, merge commits are considered. To ignore merge commits, pass the
--ignore-merge flag.
If you want to only inspect commits in a particular time range, you can use
the --since and/or --before options. For both, pass a date in the form
YYYY-MM-DD (e.g. --since 2022-01-01 or --before 2021-05-04).
By default, Branch Detective shows you one commit at a time, and waits for
you to hit enter to continue. However, if you want to see all the commits
at once, such as if you're exporting the output to a file, pass the
--show-all or -a flag to show all the missing commits at once.
branch-detective devel main --show-allBranch Detective either looks at the commit message or the SHA. To minimize false positives or false negatives due to workflow, we ignore dates and authors as part of commit matching.
This does mean that if you have multiple commits with the same message, if only one is present in the destination branch, it will not see any of the commits in the source branch with the matching commit message as missing.
You can install Branch Detective directly from PyPI via pip. (We recommend you do this in a virtual environment.)
pip install branch-detectivePlease report bugs and missing features on the Branch Detective repository. Pull requests are also encouraged!