From f34f4e80f80416f09d68656f14884988cd889ffd Mon Sep 17 00:00:00 2001 From: EricFromCanada Date: Fri, 17 Nov 2017 16:40:37 -0500 Subject: docs: rename Taps docs to match convention --- docs/How-to-Create-and-Maintain-a-Tap.md | 2 +- docs/README.md | 2 +- docs/Taps.md | 94 ++++++++++++++++++++++++++++++++ docs/brew-tap.md | 94 -------------------------------- 4 files changed, 96 insertions(+), 96 deletions(-) create mode 100644 docs/Taps.md delete mode 100644 docs/brew-tap.md (limited to 'docs') diff --git a/docs/How-to-Create-and-Maintain-a-Tap.md b/docs/How-to-Create-and-Maintain-a-Tap.md index c9a8da642..610380aa6 100644 --- a/docs/How-to-Create-and-Maintain-a-Tap.md +++ b/docs/How-to-Create-and-Maintain-a-Tap.md @@ -27,7 +27,7 @@ If it’s on GitHub, users can install any of your formulae with file here. If they want to get your tap without installing any formula at the same time, -users can add it with the [`brew tap` command](brew-tap.md). +users can add it with the [`brew tap` command](Taps.md). If it’s on GitHub, they can use `brew tap user/repo`, where `user` is your GitHub username and `homebrew-repo` your repository. diff --git a/docs/README.md b/docs/README.md index 07ff9074c..f069ae562 100644 --- a/docs/README.md +++ b/docs/README.md @@ -9,7 +9,7 @@ - [Tips and Tricks](Tips-N'-Tricks.md) - [Bottles (binary packages)](Bottles.md) -- [Taps (third-party repositories)](brew-tap.md) +- [Taps (third-party repositories)](Taps.md) - [Interesting Taps and Forks](Interesting-Taps-and-Forks.md) - [Anonymous Aggregate User Behaviour Analytics](Analytics.md) diff --git a/docs/Taps.md b/docs/Taps.md new file mode 100644 index 000000000..59825a0c9 --- /dev/null +++ b/docs/Taps.md @@ -0,0 +1,94 @@ +# Taps (third-party repositories) + +`brew tap` adds more repositories to the list of formulae that `brew` tracks, updates, +and installs from. By default, `tap` assumes that the repositories come from GitHub, +but the command isn't limited to any one location. + +## The command (`brew tap`) + +* `brew tap` without arguments lists the currently tapped repositories. For + example: + +```sh +$ brew tap +homebrew/core +mistydemeo/tigerbrew +dunn/emacs +``` + +* `brew tap ` makes a shallow clone of the repository at + https://github.com/user/repo. After that, `brew` will be able to work on + those formulae as if they were in Homebrew's canonical repository. You can + install and uninstall them with `brew [un]install`, and the formulae are + automatically updated when you run `brew update`. (See below for details + about how `brew tap` handles the names of repositories.) + +* `brew tap ` makes a shallow clone of the repository at URL. + Unlike the one-argument version, URL is not assumed to be GitHub, and it + doesn't have to be HTTP. Any location and any protocol that Git can handle is + fine. + +* Add `--full` to either the one- or two-argument invocations above, and Git + will make a complete clone rather than a shallow one. Full is the default for + Homebrew developers. + +* `brew tap --repair` migrates tapped formulae from a symlink-based to + directory-based structure. (This should only need to be run once.) + +* `brew untap user/repo [user/repo user/repo ...]` removes the given taps. The + repositories are deleted and `brew` will no longer be aware of their formulae. + `brew untap` can handle multiple removals at once. + +## Repository naming conventions and assumptions + +* On GitHub, your repository must be named `homebrew-something` in order to use + the one-argument form of `brew tap`. The prefix 'homebrew-' is not optional. + (The two-argument form doesn't have this limitation, but it forces you to + give the full URL explicitly.) + +* When you use `brew tap` on the command line, however, you can leave out the + 'homebrew-' prefix in commands. + + That is, `brew tap username/foobar` can be used as a shortcut for the long + version: `brew tap username/homebrew-foobar`. `brew` will automatically add + back the 'homebrew-' prefix whenever it's necessary. + +## Formula duplicate names + +If your tap contains a formula that is also present in +[`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine, +but it means that you must install it explicitly by default. + +If you would like to prioritize a tap over `homebrew/core`, you can use +`brew tap-pin username/repo` to pin the tap, +and use `brew tap-unpin username/repo` to revert the pin. + +Whenever a `brew install foo` command is issued, `brew` will find which formula +to use by searching in the following order: + +* pinned taps +* core formulae +* other taps + +If you need a formula to be installed from a particular tap, you can use fully +qualified names to refer to them. + +For example, you can create a tap for an alternative `vim` formula. Without +pinning it, the behaviour will be + +```sh +brew install vim # installs from homebrew/core +brew install username/repo/vim # installs from your custom repo +``` + +However if you pin the tap with `brew tap-pin username/repo`, you will need to +use `homebrew/core` to refer to the core formula. + +```sh +brew install vim # installs from your custom repo +brew install homebrew/core/vim # installs from homebrew/core +``` + +Do note that pinned taps are prioritized only when the formula name is directly +given by you, i.e. it will not influence formulae automatically installed as +dependencies. diff --git a/docs/brew-tap.md b/docs/brew-tap.md deleted file mode 100644 index 59825a0c9..000000000 --- a/docs/brew-tap.md +++ /dev/null @@ -1,94 +0,0 @@ -# Taps (third-party repositories) - -`brew tap` adds more repositories to the list of formulae that `brew` tracks, updates, -and installs from. By default, `tap` assumes that the repositories come from GitHub, -but the command isn't limited to any one location. - -## The command (`brew tap`) - -* `brew tap` without arguments lists the currently tapped repositories. For - example: - -```sh -$ brew tap -homebrew/core -mistydemeo/tigerbrew -dunn/emacs -``` - -* `brew tap ` makes a shallow clone of the repository at - https://github.com/user/repo. After that, `brew` will be able to work on - those formulae as if they were in Homebrew's canonical repository. You can - install and uninstall them with `brew [un]install`, and the formulae are - automatically updated when you run `brew update`. (See below for details - about how `brew tap` handles the names of repositories.) - -* `brew tap ` makes a shallow clone of the repository at URL. - Unlike the one-argument version, URL is not assumed to be GitHub, and it - doesn't have to be HTTP. Any location and any protocol that Git can handle is - fine. - -* Add `--full` to either the one- or two-argument invocations above, and Git - will make a complete clone rather than a shallow one. Full is the default for - Homebrew developers. - -* `brew tap --repair` migrates tapped formulae from a symlink-based to - directory-based structure. (This should only need to be run once.) - -* `brew untap user/repo [user/repo user/repo ...]` removes the given taps. The - repositories are deleted and `brew` will no longer be aware of their formulae. - `brew untap` can handle multiple removals at once. - -## Repository naming conventions and assumptions - -* On GitHub, your repository must be named `homebrew-something` in order to use - the one-argument form of `brew tap`. The prefix 'homebrew-' is not optional. - (The two-argument form doesn't have this limitation, but it forces you to - give the full URL explicitly.) - -* When you use `brew tap` on the command line, however, you can leave out the - 'homebrew-' prefix in commands. - - That is, `brew tap username/foobar` can be used as a shortcut for the long - version: `brew tap username/homebrew-foobar`. `brew` will automatically add - back the 'homebrew-' prefix whenever it's necessary. - -## Formula duplicate names - -If your tap contains a formula that is also present in -[`homebrew/core`](https://github.com/Homebrew/homebrew-core), that's fine, -but it means that you must install it explicitly by default. - -If you would like to prioritize a tap over `homebrew/core`, you can use -`brew tap-pin username/repo` to pin the tap, -and use `brew tap-unpin username/repo` to revert the pin. - -Whenever a `brew install foo` command is issued, `brew` will find which formula -to use by searching in the following order: - -* pinned taps -* core formulae -* other taps - -If you need a formula to be installed from a particular tap, you can use fully -qualified names to refer to them. - -For example, you can create a tap for an alternative `vim` formula. Without -pinning it, the behaviour will be - -```sh -brew install vim # installs from homebrew/core -brew install username/repo/vim # installs from your custom repo -``` - -However if you pin the tap with `brew tap-pin username/repo`, you will need to -use `homebrew/core` to refer to the core formula. - -```sh -brew install vim # installs from your custom repo -brew install homebrew/core/vim # installs from homebrew/core -``` - -Do note that pinned taps are prioritized only when the formula name is directly -given by you, i.e. it will not influence formulae automatically installed as -dependencies. -- cgit v1.2.3