Add a merge-base option to the buf-breaking check

[tyler-breisacher-zipline]

Feature

If I have some changes on a branch that has diverged from the main branch, to check for breaking changes, I probably want to compare against not the main branch itself, but the merge-base of the main branch and my branch. So it would be nice if the --against flag accepted .git#merge-base=main or something like that.

[emcfarlane]

The github action buf-action works in a similar way when configured with the default: use the pull_request event. This will be a merged commit view against main. Effectively masking any changes.

Adding this locally would provide an easier way to test. The current workaround being to just merge main into your feature branch before running the current check. You can also use shell expansion if running this locally: buf breaking --against ".git#ref=$(git merge-base HEAD main)". Will discuss with the team.

[tyler-breisacher-zipline]

In our case we're using this from prek which, as far as I know, does not automatically provide the merge-base commit to its hooks (in an env var or something like that), but maybe it should 🤔

[dylan-bourque]

See also #3552, which is related to the same edge case.

[doriable]

as cited on the PR submission for this, such an option goes against the UX of existing git input options and produces undue side effects to the inputs. that being said, for the pre-commit hook use-case specifically, if a comparison the merge base is needed, a repo local hook could be used/defined that would be able to handle the shell expansion:

  repos:
    - repo: local
      hooks:
        - id: buf-breaking-merge-base
          name: buf breaking (against merge-base)
          language: system
          entry: bash -c 'buf breaking --against ".git#ref=$(git merge-base HEAD "${BUF_BREAKING_BASE:-origin/main}")"' --
          types: [proto]
          pass_filenames: false
          require_serial: true

some notes on this:

• this assumes that both buf and git are available on the system
• pass_filenames: false and require_serial: true since buf breaking operates on the module/workspace rather than individual files
• ${BUF_BREAKING_BASE:-origin/main} allows for overriding the base branch as needed or defaults to origin/main
• for CI, there needs to be enough history for the merge-base to exist, so an appropriate clone is needed with the requisite fetch depth