From d31b7fe86eb4e6cdc9907574b34493927df27d8e Mon Sep 17 00:00:00 2001 From: Eric Knibbe Date: Tue, 15 Jul 2025 13:33:57 -0400 Subject: [PATCH] Add docs for `brew alias` command --- Library/Homebrew/aliases/alias.rb | 8 +-- Library/Homebrew/cmd/alias.rb | 5 +- completions/fish/brew.fish | 2 +- completions/zsh/_brew | 2 +- docs/Manpage.md | 4 +- docs/Tips-and-Tricks.md | 85 ++++++++++++++++++++++++++++--- manpages/brew.1 | 4 +- 7 files changed, 91 insertions(+), 19 deletions(-) diff --git a/Library/Homebrew/aliases/alias.rb b/Library/Homebrew/aliases/alias.rb index 37e95d3e8a..143c760784 100644 --- a/Library/Homebrew/aliases/alias.rb +++ b/Library/Homebrew/aliases/alias.rb @@ -75,14 +75,16 @@ module Homebrew EOS else <<~EOS - # + #: * `#{name}` [args...] + #: `brew #{name}` is an alias for *command* + # This is a Homebrew alias script. It'll be called when the user # types `brew #{name}`. Any remaining arguments are passed to # this script. You can retrieve those with $*, or only the first # one with $1. Please keep your script on one line. - # TODO Replace the line below with your script - echo "Hello I'm brew alias "#{name}" and my args are:" $1 + # TODO: Replace the line below with your script + echo "Hello I'm 'brew "#{name}"' and my args are:" $* EOS end diff --git a/Library/Homebrew/cmd/alias.rb b/Library/Homebrew/cmd/alias.rb index 85272c67de..35a9a546e9 100755 --- a/Library/Homebrew/cmd/alias.rb +++ b/Library/Homebrew/cmd/alias.rb @@ -8,13 +8,14 @@ module Homebrew module Cmd class Alias < AbstractCommand cmd_args do - usage_banner "`alias` [ ... | =]" + usage_banner "`alias` [`--edit`] [|=]" description <<~EOS - Show existing aliases. If no aliases are given, print the whole list. + Show an alias's command. If no alias is given, print the whole list. EOS switch "--edit", description: "Edit aliases in a text editor. Either one or all aliases may be opened at once. " \ "If the given alias doesn't exist it'll be pre-populated with a template." + named_args max: 1 end diff --git a/completions/fish/brew.fish b/completions/fish/brew.fish index 23c358b7ae..544da34d88 100644 --- a/completions/fish/brew.fish +++ b/completions/fish/brew.fish @@ -319,7 +319,7 @@ __fish_brew_complete_arg 'abv; and not __fish_seen_argument -l cask -l casks' -a __fish_brew_complete_arg 'abv; and not __fish_seen_argument -l formula -l formulae' -a '(__fish_brew_suggest_casks_all)' -__fish_brew_complete_cmd 'alias' 'Show existing aliases' +__fish_brew_complete_cmd 'alias' 'Show an alias\'s command' __fish_brew_complete_arg 'alias' -l debug -d 'Display any debugging information' __fish_brew_complete_arg 'alias' -l edit -d 'Edit aliases in a text editor. Either one or all aliases may be opened at once. If the given alias doesn\'t exist it\'ll be pre-populated with a template' __fish_brew_complete_arg 'alias' -l help -d 'Show this message' diff --git a/completions/zsh/_brew b/completions/zsh/_brew index 5d0413c957..e2064824d7 100644 --- a/completions/zsh/_brew +++ b/completions/zsh/_brew @@ -139,7 +139,7 @@ __brew_internal_commands() { '--prefix:Display Homebrew'\''s install path' '--repository:Display where Homebrew'\''s Git repository is located' '--version:Print the version numbers of Homebrew, Homebrew/homebrew-core and Homebrew/homebrew-cask (if tapped) to standard output' - 'alias:Show existing aliases' + 'alias:Show an alias'\''s command' 'analytics:Control Homebrew'\''s anonymous aggregate user behaviour analytics' 'audit:Check formula or cask for Homebrew coding style violations' 'autoremove:Uninstall formulae that were only installed as a dependency of another formula and are now no longer needed' diff --git a/docs/Manpage.md b/docs/Manpage.md index 138410b99e..485221bd24 100644 --- a/docs/Manpage.md +++ b/docs/Manpage.md @@ -102,9 +102,9 @@ If no search term is provided, all locally available formulae are listed. ## COMMANDS -### `alias` \[*`alias`* ... \| *`alias`*=*`command`*\] +### `alias` \[`--edit`\] \[*`alias`*\|*`alias`*=*`command`*\] -Show existing aliases. If no aliases are given, print the whole list. +Show an alias's command. If no alias is given, print the whole list. `--edit` diff --git a/docs/Tips-and-Tricks.md b/docs/Tips-and-Tricks.md index b3aedef367..9f63453288 100644 --- a/docs/Tips-and-Tricks.md +++ b/docs/Tips-and-Tricks.md @@ -1,5 +1,5 @@ --- -last_review_date: "1970-01-01" +last_review_date: 2025-07-15 redirect_from: - /Tips-N'-Tricks --- @@ -26,7 +26,7 @@ Sometimes it's faster to download a file via means other than the strategies tha Downloads are saved in the `downloads` subdirectory of Homebrew's cache directory (as specified by `brew --cache`, e.g. `~/Library/Caches/Homebrew`) and renamed as `---`. The command `brew --cache --build-from-source ` will print the expected path of the cached download, so after downloading the file, you can run `mv the_tarball "$(brew --cache --build-from-source )"` to relocate it to the cache. -You can also pre-cache the download by using the command `brew fetch ` which also displays the SHA-256 hash. This can be useful for updating formulae to new versions. +You can also pre-cache the download by using the command `brew fetch ` which also displays its SHA-256 hash. This can be useful for updating formulae to new versions. ## Install stuff without the Xcode CLT @@ -49,12 +49,17 @@ brew install --only-dependencies $ brew irb ==> Interactive Homebrew Shell Example commands available with: `brew irb --examples` -irb(main):001:0> Formulary.factory("ace").methods - Object.methods -=> [:install, :test, :test_defined?, :sbin, :pkgshare, :elisp, -:frameworks, :kext_prefix, :any_version_installed?, :etc, :pkgetc, +brew(main):001> Formulary.factory("ace").methods - Object.methods +=> +[:test, + :install, + :valid_platform?, ... -:on_macos, :on_linux, :debug?, :quiet?, :verbose?, :with_context] -irb(main):002:0> + :debug?, + :verbose?, + :quiet?] + [:install, :test, :test_defined?, :sbin, :pkgshare, :elisp, +brew(main):002> ``` ## Hide the beer mug emoji when finishing a build @@ -89,6 +94,70 @@ $ brew install --cask --adopt textmate 🍺 textmate was successfully installed! ``` +## Define aliases for Homebrew commands + +Use [`brew alias`](Manpage.md#alias---edit-aliasaliascommand) to define custom commands that run other commands in `brew` or your shell, similar to the `alias` shell builtin. + +```shell +# Add aliases +$ brew alias ug='upgrade' +$ brew alias i='install' + +# Print all aliases +$ brew alias + +# Print one alias +$ brew alias i + +# Use your aliases like any other command +$ brew i git + +# Remove an alias +$ brew unalias i + +# Aliases can include other aliases +$ brew alias show='info' +$ brew alias print='show' +$ brew print git # will run `brew info git` +``` + +Note that names of stock Homebrew commands can't be used as aliases. + +All aliased commands are prefixed with `brew`, unless they start with `!` or `%`: + +```shell +$ brew alias ug='upgrade' +# `brew ug` → `brew upgrade` + +$ brew alias status='!git status' +# `brew status` → `git status` +``` + +You may need single quotes to prevent your shell from interpreting `!`, but `%` will work for both quote types. + +```shell +# Use shell expansion to preserve a local variable +$ mygit=/path/to/my/git +$ brew alias git="%$mygit" +# `brew git status` → `/path/to/my/git status` +``` + +Aliases can be opened in `$EDITOR` with the `--edit` flag. + +```shell +# Edit alias 'brew foo', creating if necessary +$ brew alias --edit foo +# Create and edit alias 'brew foo' +$ brew alias --edit foo=bar + +# This works too +$ brew alias foo --edit +$ brew alias foo=bar --edit + +# Open all aliases in $EDITOR +$ brew alias --edit +``` + ## Editor plugins ### Visual Studio Code @@ -119,7 +188,7 @@ Terminal needs an extra hint on where to find manpages installed by Homebrew bec ```sh sudo mkdir -p /usr/local/etc/man.d -echo "MANPATH /opt/homebrew/share/man" | sudo tee -a /usr/local/etc/man.d/homebrew.man.conf +echo "MANPATH $(brew --prefix)/share/man" | sudo tee -a /usr/local/etc/man.d/homebrew.man.conf ``` If you're using Homebrew on macOS Intel, you should also fix permissions afterwards with: diff --git a/manpages/brew.1 b/manpages/brew.1 index 1d22fcab7a..1678fe2dbe 100644 --- a/manpages/brew.1 +++ b/manpages/brew.1 @@ -62,8 +62,8 @@ List all installed formulae\. .SS "\fBsearch\fP \fR[\fItext\fP|\fB/\fP\fItext\fP\fB/\fP]" Perform a substring search of cask tokens and formula names for \fItext\fP\&\. If \fItext\fP is flanked by slashes, it is interpreted as a regular expression\. The search for \fItext\fP is extended online to \fBhomebrew/core\fP and \fBhomebrew/cask\fP\&\. If no search term is provided, all locally available formulae are listed\. .SH "COMMANDS" -.SS "\fBalias\fP \fR[\fIalias\fP \.\.\. | \fIalias\fP=\fIcommand\fP]" -Show existing aliases\. If no aliases are given, print the whole list\. +.SS "\fBalias\fP \fR[\fB\-\-edit\fP] \fR[\fIalias\fP|\fIalias\fP=\fIcommand\fP]" +Show an alias\[u2019]s command\. If no alias is given, print the whole list\. .TP \fB\-\-edit\fP Edit aliases in a text editor\. Either one or all aliases may be opened at once\. If the given alias doesn\[u2019]t exist it\[u2019]ll be pre\-populated with a template\.