brew-pin: prevent selected formulae from upgrade.

* Added `pin` et. al. to manpage.
* Added `brew pin` to `brew.1` * Added `brew unpin` to `brew.1`
* Added `brew list --pinned` to `brew.1`
* Added information about frozen formulae to `brew upgrade` in `brew.1`
* Added `pin` et.al. to completion scripts.
* Unpin formulae when uninstalling them
* Unpin and re-pin formulae when upgrading (avoids stale symlink)

References Homebrew/homebrew#18386.
Closes Homebrew/homebrew#18515.

Signed-off-by: Mike McQuaid <mike@mikemcquaid.com>

1 files changed, 14 insertions, 3 deletions

diff --git a/share/man/man1/brew.1 b/share/man/man1/brew.1
index 952e87876..96886e6b7 100644
--- a/share/man/man1/brew.1
+++ b/share/man/man1/brew.1
@@ -215,7 +215,7 @@ If \fB\-\-overwrite\fR is passed, Homebrew will delete files which already exist
 If \fB\-\-dry\-run\fR or \fB\-n\fR is passed, Homebrew will list all files which would be linked or which would be deleted by \fBbrew link \-\-overwrite\fR, but will not actually link or delete any files\.
 .
 .TP
-\fBls, list [\-\-unbrewed] [\-\-versions]\fR [\fIformulae\fR]
+\fBls, list [\-\-unbrewed] [\-\-versions] [\-\-pinned]\fR [\fIformulae\fR]
 Without any arguments, list all installed formulae\.
 .
 .IP
@@ -227,6 +227,9 @@ If \fB\-\-unbrewed\fR is passed, list all files in the Homebrew prefix not insta
 .IP
 If \fB\-\-versions\fR is passed, show the version number for installed formulae, or only the specified formulae if \fIformulae\fR are given\.
 .
+.IP
+If \fB\-\-pinned\fR is passed, show the versions of pinned formulae, or only the specified (pinned) formulae if \fIformulae\fR are given\. See also [\fBpin\fR][], [\fBunpin\fR][]\.
+.
 .TP
 \fBlog [git\-log\-options]\fR \fIformula\fR \.\.\.
 Show the git log for the given formulae\. Options that \fBgit\-log\fR(1) recognizes can be passed before the formula list\.
@@ -259,6 +262,10 @@ Show formulae that have an updated version available\.
 If \fB\-\-quiet\fR is passed, list only the names of outdated brews\. Otherwise, the versions are printed as well\.
 .
 .TP
+\fBpin\fR \fIformulae\fR
+Pin the specified \fIformulae\fR, preventing them from being upgraded when issuing the \fBbrew upgrade\fR command without arguments\. See also [\fBunpin\fR][]\.
+.
+.TP
 \fBprune\fR
 Remove dead symlinks from the Homebrew prefix\. This is generally not needed, but can be useful when doing DIY installations\.
 .
@@ -302,6 +309,10 @@ Example: \fBbrew install jruby && brew test jruby\fR
 Unsymlink \fIformula\fR from the Homebrew prefix\. This can be useful for temporarily disabling a formula: \fBbrew unlink foo && commands && brew link foo\fR\.
 .
 .TP
+\fBunpin\fR \fIformulae\fR
+Unpin \fIformulae\fR, allowing them to be upgraded by \fBbrew upgrade\fR\. See also [\fBpin\fR][]\.
+.
+.TP
 \fBuntap\fR \fItap\fR
 Remove a tapped repository\.
 .
@@ -314,10 +325,10 @@ If \fB\-\-rebase\fR is specified then \fBgit pull \-\-rebase\fR is used\.
 .
 .TP
 \fBupgrade\fR [\fIformulae\fR]
-Upgrade outdated brews\.
+Upgrade outdated, non\-pinned brews\.
 .
 .IP
-If \fIformulae\fR are given, upgrade only the specified brews\.
+If \fIformulae\fR are given, upgrade only the specified brews (but do so even if they are pinned; see [\fBpin\fR][], [\fBunpin\fR][])\.
 .
 .TP
 \fBuses [\-\-installed] [\-\-recursive]\fR \fIformula\fR