completions: make opt-in only

[Rylan12]

• Have you followed the guidelines in our Contributing document?
• Have you checked to ensure there aren't other open Pull Requests for the same change?
• Have you added an explanation of what your changes do and why you'd like us to include them?
• Have you written new tests for your changes? Here's an example.
• Have you successfully run brew style with your changes locally?
• Have you successfully run brew typecheck with your changes locally?
• Have you successfully run brew tests with your changes locally?
• Have you successfully run brew man locally and committed any changes?

---

This PR adds a brew completions command and makes linking completions opt-in only per discussion in #10229.

Once this PR is merged, users will see a message in brew update informing them that completions are no longer linked. It will direct them to run brew completions link to link completions. The user can choose whether completions are linked by running brew completions link or brew completions unlink. They can check whether completions are linked by running brew completions or brew completions status.

CC @MikeMcQuaid

[BrewTestBot]

Review period will end on 2021-01-11 at 16:14:49 UTC.

[MikeMcQuaid]

Thanks @Rylan12! Sorry if my communication around this has been sub-optimal.

[Rylan12]

Ah, looks like I did misunderstand a little. You're saying we should automatically link completions for built-in commands just not for third-party taps, right?

If so, this PR isn't quite ready yet because it stops all linking.

[MikeMcQuaid]

Ah, looks like I did misunderstand a little. You're saying we should automatically link completions for built-in commands just not for third-party taps, right?

Yes, sorry!

[MikeMcQuaid]

Ah, looks like I did misunderstand a little. You're saying we should automatically link completions for built-in commands just not for third-party taps, right?

Essentially: if we (Homebrew) control the code: it's enabled by default. If we don't: it requires some user action.

[BrewTestBot]

Review period ended.

[Rylan12]

Okay, I've updated to still link completions from official taps automatically.

Additionally, the message only shows if there are completions in non-official taps available.

[MikeMcQuaid]

Looking good! Some wording changes.

[MikeMcQuaid]

Thanks @Rylan12, great work! Some comments but all optional/non-blocking.

[MikeMcQuaid]

At this point: let's either not use multiple describes in the test or disable this cop.

[Rylan12]

Which is preferable? It would be relatively easy to just add a single describe that encompasses the entire file for each of these. I don't think it would cause much additional clutter at least to the cmd/*, dev-cmd/*, rubocops/* files. I haven't looked at the others.

Alternatively, we can cut down the number of exclusions by using:

Exclude:
  - 'ENV_spec.rb'
  - 'cleanup_spec.rb'
  - 'cmd/*.rb'
  - 'dependency_spec.rb'
  - 'dev-cmd/*.rb'
  - 'download_strategies_spec.rb'
  - 'exceptions_spec.rb'
  - 'formula_support_spec.rb'
  - 'inreplace_spec.rb'
  - 'language/python_spec.rb'
  - 'options_spec.rb'
  - 'os/mac/mach_spec.rb'
  - 'patch_spec.rb'
  - 'rubocops/*.rb'
  - 'software_spec_spec.rb'
  - 'tap_spec.rb'
  - 'utils/git_spec.rb'
  - 'version_spec.rb'

That doesn't really reduce the number of offenses it just cleans up the exclusion list.

Can this go in a separate PR (which I'm happy to do)?

For now, I'll add new files with only a single describe so this isn't increased (although the reason the number jumped so much here is not that I added 5 new offenses, it was just out of date. I only added one)

[MikeMcQuaid]

Which is preferable? It would be relatively easy to just add a single describe that encompasses the entire file for each of these. I don't think it would cause much additional clutter at least to the cmd/*, dev-cmd/*, rubocops/* files. I haven't looked at the others.

Either is fine with me. Slight preference for "doing what the cop wants".

Can this go in a separate PR (which I'm happy to do)?

Definitely (and thanks for offering)!

For now, I'll add new files with only a single describe so this isn't increased (although the reason the number jumped so much here is not that I added 5 new offenses, it was just out of date. I only added one)

Perfect 👍🏻