Introduce bundle list --format=json

[schneems]

What was the end-user or developer problem that led to this PR?

I need to know what versions of gems are installed for a given application programmatically. I'm currently parsing the bundle list output, but I'm worried that the format may change in the future.

What is your fix for the problem, implemented in this PR?

Introduce a stable, machine-readable formatting output to this command via adding a --format=json flag.

More

The bundle list command is a convenient way for human to know what gems and versions are available. By introducing a --format=json option, we can provide the same information to machines in a stable format that is robust to UI additions or modifications. It indirectly supports Gemfile.lock modifications by discouraging external tools from attempting to parse that format.

This addition allows for the scripting of installation tools, such as buildpacks, that wish to branch logic based on gem versions. For example:

require "json"

command = "bundle list --format=json"
output = `#{command}`
raise "Command `#{command}` errored: #{output}" unless $?.success?

railties = JSON.parse(output).find {|gem| gem["name"] == railties }
if railties && Gem::Version.new(railties["version"]) >= Gem::Version.new("7")
  puts "Using Rails greater than 7!"
end

The top level is an object with a single key, "gems", this structure allows us to add other information in the future (should we desire) without having to change the json schema.

This JSON format is also useful in a bash scripting context, where command-line tools such as jq are commonly available to manipulate and extract information.

Make sure the following tasks are checked

• Describe the problem / feature
• Write tests for features and bug fixes
• Write code to solve the problem
• Make sure you follow the current code style and write meaningful commit messages without tags

[soulcutter]

I like this idea a lot.

What about --format=json as an alternate syntax? It opens the door for other formats like csv or json lines etc. I'm not sure if there's a most-common name for that option, I've also seen --output json off the top of my head.

[schneems]

What about --format=json as an alternate syntax?

Short: Seems good. I updated in a new commit.

Longer: For some numbers, I searched on GitHub:

• --format= 766K hits https://github.com/search?q=%2F--format%3D%2F&type=code
• --output= 690K hits https://github.com/search?q=%2F--output%3D%2F&type=code
• --json 672K https://github.com/search?q=%2F--json%2F&type=code

Seems that --format= is the preferred syntax in the community. As an alternative, could later add --xml etc. The only benefit I see to unifying behind a flag is this would be invalid --json --xml but that's not possible via --format=json (though you could --format=json --format=xml), but IIRC that's protected at the top level (thor).

[edmorley]

Seems that --format= is the preferred syntax in the community

As another couple of datapoints, --format also seems common with Ruby-specific tools too, eg:
https://rspec.info/features/3-12/rspec-core/command-line/format-option/
https://docs.rubocop.org/rubocop/1.76/formatters.html

[schneems]

I'm interested in any feedback that could help advance or close this out. Baring strong blockers or actionable requests: a temperature reading of the feature is helpful too. Does this seem reasonable (warm) or does something about it make you say "ick" (ice cold)?

[deivid-rodriguez]

I like this and I'm happy to introduce it, just did not find time to review it.

Naming seems also fine, some commands already have a --parseable flag, but I don't think that prescribes a specific format, just promises a "minimal formatting for more parseable output". I think something more specific like --format=json is better.

[schneems]

I'm unsure on timeline, but it would be nice to get this in before bundler 4 (if possible).

[deivid-rodriguez]

I commented some super minor nitpicks, but this PR looks good!

[deivid-rodriguez]

This looks good to me! Do you mind squashing all commits to a single one?

[schneems]

Squashed and rebased, waiting for tests to run. Going to resolve prior comments.

[schneems]

CI is all green. Thanks for the review and your work 🙏

[deivid-rodriguez]

No problem, I'll merge on Monday just to leave other maintainers some more time in case they have feedback.

[deivid-rodriguez]

Thank you!