Policy guidance: renaming the atomgit-cli executable from ag to ag-cli

[mudongliang]

Output of brew config

HOMEBREW_VERSION: 7.0.4-47-g32b5f52
ORIGIN: https://github.com/Homebrew/brew
HEAD: 32b5f52a42555d8004f9273a716baea06971fdcb
Last commit: 2 days ago
Branch: main
Core tap: N/A
Core cask tap: N/A
HOMEBREW_PREFIX: /opt/homebrew
Homebrew Ruby: 4.0.7 => /opt/homebrew/Library/Homebrew/vendor/portable-ruby/4.0.7/bin/ruby
CPU: 14-core 64-bit arm_brava
Clang: 21.0.0 build 2100
Git: 2.50.1 => /Library/Developer/CommandLineTools/usr/bin/git
Curl: 8.7.1 => /usr/bin/curl
macOS: 26.6.2-arm64
CLT: 26.6.0.0.1781586589
Xcode: N/A
Rosetta 2: false

Output of brew doctor

Please note that these warnings are just used to help the Homebrew maintainers
with debugging if you file an issue. If everything you use Homebrew for is
working fine: please don't worry or file an issue; just ignore this. Thanks!

Warning: A newer Command Line Tools release is available.
Update them from Software Update in System Settings.

If that doesn't show you any updates, run:
  sudo rm -rf /Library/Developer/CommandLineTools
  sudo xcode-select --install

Alternatively, manually download them from:
  https://developer.apple.com/download/all/.
You should download the Command Line Tools for Xcode 26.6.
This is a Tier 2 configuration:
  https://docs.brew.sh/Support-Tiers#tier-2
You can report issues with Tier 2 configurations to Homebrew/* repositories!
  https://docs.brew.sh/Troubleshooting
Read the above document before opening any issues or PRs.

Description of issue

Hi Homebrew maintainers,

I am the upstream maintainer of AtomGit CLI, which
is currently distributed through the atomgit-cli
formula.

The formula currently installs our executable as ag. However, [the_silver_searcher](https://
formulae.brew.sh/formula/the_silver_searcher) also provides an essential executable named ag. This
prevents the two formulae from being linked at the same time and causes a similar file conflict for Linux
distribution maintainers.

We are therefore considering an upstream rename in our next stable release, currently planned for mid-
October 2026:

• The canonical executable would change from ag to ag-cli.
• We would not install an ag compatibility symlink, because that would preserve the original conflict.
• The project and Homebrew formula names would remain atomgit-cli.
• The configuration directory is already named ~/.config/ag-cli, so the new executable name would also
  be consistent with the existing configuration layout.
• Upstream release archives, installers, shell completions, documentation, npm launchers, self-update
  detection, and tests would all be updated together.
• The Homebrew formula test would be updated to invoke ag-cli.

Before implementing this breaking change, we would appreciate guidance on the preferred Homebrew
migration:

1. Is it acceptable for an existing formula to change its installed executable from ag to ag-cli as
   part of a new upstream stable release?
2. Does Homebrew prefer any additional migration handling?
3. Is there anything else that should be included in the corresponding formula update PR?

Our preference is to resolve the collision upstream instead of adding a permanent conflicts_with
declaration, since both commands are essential to their respective projects and can coexist cleanly after
the rename.

Thank you for your guidance.

[SMillerDev]

Our policy is very simple on this: we name it whatever upstream names their executables. If you change them in the build script, ours will change right along with it.

[mudongliang]

thanks very much. I have submitted the PR: Homebrew/homebrew-core#316748