update documentation

share/doc/homebrew/brew-tap.md

@@ -54,14 +54,39 @@ edavis/emacs
 
 ## Formula duplicate names
 
-If your tap contains a formula that is also present in master, that's fine, but
+If your tap contains a formula that is also present in master, that's fine,
-it means that you must install it explicitly.
+but it means that you must install it explicitly by default.
 
-For example, you can create a tap for an alternative `vim` formula, but in that
+If you would like to prioritize a tap over master, you can use
-case when you install from there you must run the command with a more explicit
+`brew tap-pin username/repo` to pin the tap,
-installation target:
+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 formulas
+* 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 behavior will be
 
 ```bash
 brew install vim                     # installs from Homebrew/homebrew
 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/homebrew` to refer to the core formula.
+
+```bash
+brew install vim                     # installs from your custom repo
+brew install homebrew/homebrew/vim   # installs from Homebrew/homebrew
+```
+
+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.