Add docs for brew alias command

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
 

Library/Homebrew/cmd/alias.rb

@@ -8,13 +8,14 @@ module Homebrew
   module Cmd
     class Alias < AbstractCommand
       cmd_args do
-        usage_banner "`alias` [<alias> ... | <alias>=<command>]"
+        usage_banner "`alias` [`--edit`] [<alias>|<alias>=<command>]"
         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
 

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'

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'

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`
 

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 `<url-hash>--<formula>-<version>`. The command `brew --cache --build-from-source <formula>` 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 <formula>)"` to relocate it to the cache.
 
-You can also pre-cache the download by using the command `brew fetch <formula>` 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 <formula>` 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 <formula>
 $ 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:

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\.