docs/Taps.md

   1 ---
   2 last_review_date: "1970-01-01"
   3 ---
   4
   5 # Taps (Third-Party Repositories)
   6
   7 The `brew tap` command adds more repositories to the list of formulae that Homebrew tracks, updates,
   8 and installs from. By default, `tap` assumes that the repositories come from GitHub,
   9 but the command isn't limited to any one location.
  10
  11 ## The `brew tap` command
  12
  13 * `brew tap` without arguments lists all currently tapped repositories. For
  14   example:
  15
  16   ```console
  17   $ brew tap
  18   homebrew/cask
  19   homebrew/core
  20   petere/postgresql
  21   ```
  22
  23 * `brew tap <user>/<repo>` makes a clone of the repository at
  24   `https://github.com/<user>/homebrew-<repo>` into `$(brew --repository)/Library/Taps`.
  25   After that, `brew` will be able to work with those formulae as if they were in Homebrew's
  26   [homebrew/core](https://github.com/Homebrew/homebrew-core) canonical repository.
  27   You can install and uninstall them with `brew [un]install`, and the formulae are
  28   automatically updated when you run `brew update`. (See below for details
  29   about how `brew tap` handles the names of repositories.)
  30
  31 * `brew tap <user>/<repo> <URL>` makes a clone of the repository at _URL_.
  32   Unlike the one-argument version, _URL_ is not assumed to be GitHub, and it
  33   doesn't have to be HTTP. Any location and any protocol that Git can handle is
  34   fine, although non-GitHub taps require running `brew tap --force-auto-update <user>/<repo>`
  35   to enable automatic updating.
  36
  37 * `brew tap --repair` migrates tapped formulae from a symlink-based to
  38   directory-based structure. (This should only need to be run once.)
  39
  40 * `brew untap user/repo [user/repo user/repo ...]` removes the given taps. The
  41   repositories are deleted and `brew` will no longer be aware of their formulae.
  42   `brew untap` can handle multiple removals at once.
  43
  44 ## Repository naming conventions and assumptions
  45
  46 On GitHub, your repository must be named `homebrew-something` to use
  47 the one-argument form of `brew tap`. The prefix "homebrew-" is not optional.
  48 (The two-argument form doesn't have this limitation, but it forces you to
  49 give the full URL explicitly.)
  50
  51 When you use `brew tap` on the command line, however, you can leave out the
  52 "homebrew-" prefix in commands. That is, `brew tap username/foobar` can be used as a shortcut for the long
  53 version: `brew tap username/homebrew-foobar`. `brew` will automatically add
  54 back the "homebrew-" prefix whenever it's necessary.
  55
  56 ## Formula with duplicate names
  57
  58 If your tap contains a formula that is also present in
  59 [homebrew/core](https://github.com/Homebrew/homebrew-core), that's fine,
  60 but you would need to specify its fully qualified name in the form
  61 `<user>/<repo>/<formula>` to install your version.
  62
  63 Whenever a `brew install foo` command is issued, `brew` selects which formula
  64 to use by searching in the following order:
  65
  66 * core formulae
  67 * other taps
  68
  69 If you need a formula to be installed from a particular tap, you can use fully
  70 qualified names to refer to them.
  71
  72 If you were to create a tap for an alternative `vim` formula, the behaviour would be:
  73
  74 ```sh
  75 brew install vim                     # installs from homebrew/core
  76 brew install username/repo/vim       # installs from your custom repository
  77 ```
  78
  79 As a result, we recommend you give new names to customized formulae if you want to make
  80 them easier to install. Note that there is (intentionally) no way of replacing
  81 dependencies of core formulae with those from other taps.