Keep `bundle` as `bundle install` by default

[eregon]

Describe the problem as clearly as you can

What many people use is:

$ bundle

to "bundle", i.e., to install gems (and not bundle install or bundle i).
This is naturally the main action of Bundler, and in fact for projects which do require 'bundler/setup' this is potentially the only interaction you have with Bundler.

But on Bundler 4 that broke:

$ ruby -v
ruby 4.0.0preview2 (2025-11-17 master 4fa6e9938c) +PRISM [x86_64-linux]
$ undle
Bundler version 4.0.0.dev (2025-11-26 commit unknown)

Bundler commands:

  Primary commands:
    bundle install [OPTIONS]    # Install the current environment to the system
    bundle update [OPTIONS]     # Update the current environment
    bundle cache [OPTIONS]      # Locks and then caches all of the gems into vendor/cache
    bundle exec [OPTIONS]       # Run the command in context of the bundle
    bundle config NAME [VALUE]  # Retrieve or set a configuration value
    bundle help [COMMAND]       # Describe available commands or one specific command

  Utilities:
    bundle add GEM VERSION         # Add gem to Gemfile and run bundle install
    bundle binstubs GEM [OPTIONS]  # Install the binstubs of the listed gem
    bundle check [OPTIONS]         # Checks if the dependencies listed in Gemfile are satisfied by currently installed gems
    bundle clean [OPTIONS]         # Cleans up unused gems in your bundler directory
    bundle console [GROUP]         # Opens an IRB session with the bundle pre-loaded
    bundle doctor [OPTIONS]        # Checks the bundle for common problems
    bundle env                     # Print information about the environment Bundler is running under
    bundle fund [OPTIONS]          # Lists information about gems seeking funding assistance
    bundle gem NAME [OPTIONS]      # Creates a skeleton for creating a rubygem
    bundle info GEM [OPTIONS]      # Show information for the given gem
    bundle init [OPTIONS]          # Generates a Gemfile into the current working directory
    bundle issue                   # Learn how to report an issue in Bundler
    bundle licenses                # Prints the license of all gems in the bundle
    bundle list                    # List all gems in the bundle
    bundle lock                    # Creates a lockfile without installing
    bundle open GEM                # Opens the source directory of the given bundled gem
    bundle outdated GEM [OPTIONS]  # List installed gems with newer versions available
    bundle platform [OPTIONS]      # Displays platform compatibility information
    bundle plugin                  # Manage the bundler plugins
    bundle pristine [GEMS...]      # Restores installed gems to pristine condition
    bundle remove [GEM [GEM ...]]  # Removes gems from the Gemfile
    bundle show GEM [OPTIONS]      # Shows all gems that are part of the bundle, or the path to a given gem
    bundle version                 # Prints Bundler version information

Options:
      [--no-color]                                   # Disable colorization in output
  -r, [--retry=NUM]                                  # Specify the number of times you wish to attempt network commands
  -V, [--verbose], [--no-verbose], [--skip-verbose]  # Enable verbose output mode

Adding to the confusion, this is not even the same output as bundle --help/bundle help.
So it seems the issue It uses "plain thor help" over our "enhanced man based help". from #8786 hasn't been solved.

More confusing is if there is a Gemfile.lock with an older version of Bundler, (the command) bundle still doesn't work, but it starts to work after a bundle install because that will install the older Bundler.
That means it's very easy to get from a situation of "it works" to "it doesn't" because e.g. removing the Gemfile.lock.
If using e.g. BUNDLE_PATH: "vendor/bundle" it's even more complicated as the older Bundler gets installed under that path, and so just rm -r vendor/bundle would also make the problem appear again.

Then the default got back to install and a warning in #9092.

$ bundle
In the next version of Bundler, running `bundle` without argument will no longer run `bundle install`.
Instead, the `help` command will be displayed.

If you'd like to keep the previous behaviour please run `bundle config set default_cli_command install --global`.
Fetching gem metadata from https://rubygems.org/...........
...

I think the default should simply remain to install forever.

As far as I know, it's a misconception to expect that command shows the help.
Instead, command --help or man command shows the help, that's the standard.
There are plenty of commands where running command doesn't show the help, e.g. cat, ls, cd, echo, ruby, etc.

Asking every Rubyist to bundle config set default_cli_command install --global is similar to asking every Rubyist to add a new magic comment on top of their Ruby files (though needed less frequently, but still once per machine and error-prone), it shouldn't be necessary, the sensible default is already clearly established for many years and that's bundle does bundle install.
A few people might run bundle expecting the help, and that will be an opportunity for them to learn that's not the proper way to get the help for a command (in general, not just for Bundler).

[st0012]

I agree with this proposal.

Instead, command --help or man command shows the help, that's the standard.
There are plenty of commands where running command doesn't show the help, e.g. cat, ls, cd, echo, ruby, etc.

Yeah totally agree on this. We're not exactly matching any golden standard with the breaking change anyway. It's asking existing users to pay the price and interrupting existing workflows or even tools (e.g. CI actions using bundle instead of bundle install) for very little benefit.

[byroot]

I also agree with this.

One thing though, is that I think one point in rubygems/bundler#5725 is valid is that the error when invoking bundler from a directory without a Gemfile is a bit too terse:

$ cd /tmp/; bundle
Could not locate Gemfile

I think printing the help on such error would go a long way to solve the original concern without throwing off all experienced people.

[eightbitraptor]

I also agree with this proposal.

The GNU project standardised long form option switches in the 90's. To that end most command line tools support --help and --version. This is an established pattern, I don't think it's unreasonable to expect users to use --help if they are unsure how to use the tool.

bundle automatically running bundle install is a deeply entrenched convention, and even makes grammatical sense, since bundle can be a verb.

I do agree with @byroot that the error message when no Gemfile exists is too terse.

I would personally prefer an alternative, which is that bundle should do bundle check || bundle install so as to only bundle if necessary. In that way if the users wants to force an install, they can run bundle install explicitly, but for the sake of this ticket we should just revert to the old behaviour.

[byroot]

that bundle should do bundle check || bundle install so as to only bundle if necessary.

Does that actually make any difference?

I guess bundle check is very slightly less verbose when there's nothing to install:

$ bundle
Bundle complete! 82 Gemfile dependencies, 244 gems now installed.
Use `bundle info [gemname]` to see where a bundled gem is installed.
1 installed gem you directly depend on is looking for funding.
  Run `bundle fund` for details

versus:

$ bundle check
The Gemfile's dependencies are satisfied

Is that what you meant?

[byroot]

I opened a PR to get rid of the warning: #9125

I tried to implement the extra behavior of printing the help when invoked with no subcommand, but Thor doesn't make that easy, so I kinda gave up.

[byroot]

so I kinda gave up.

Actually I had a last minute idea that seem to work: 8c8f1ab

I can submit a PR for it if @hsbt think it's worth it.

[colby-swandale]

I agree with the overall points here. The warning have come a bit too late to inform people of the change, and we don't have much time to ensure a consistent experience across the ecosystem before this impacts people.

[hsbt]

There are plenty of commands where running command doesn't show the help, e.g. cat, ls, cd, echo, ruby, etc.

They are not fair comparison targets.

npm, pnpm, pip3, cargo, go (mod) and gem prints help or usage(see also rubygems/bundler#5725 (comment)). In my experience, bundle and yarn invoke to package download and installation action. I'm always surprised to use yarn because I use bundle i instead of bundle.

This change for new users who are familir with above package manager. I know many of Rubyists felt some confusion or frustration because we provide the feature of changing default command option.

I've often said that what Ruby needs for the future is newcomers, but I don't want to raise unnecessary barriers with this kind of tool behavior.

Asking every Rubyist to bundle config set default_cli_command install --global is similar to asking every Rubyist to add a new magic comment on top of their Ruby files

I think discussions about magic comments are different issue. At least I always ignore them.

Improving the user experience when a Gemfile is missing or contains mixed versions should be prioritized.

[hsbt]

How about #9126?

Instead of issuing warnings every time, we'll only send guidance during the first instance. Is this still considered annoying?