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 #18386.
Closes #18515.

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

1 files changed, 36 insertions, 0 deletions

diff --git a/Library/Homebrew/formula_pin.rb b/Library/Homebrew/formula_pin.rb
new file mode 100644
index 000000000..cdffd7fc0
--- /dev/null
+++ b/Library/Homebrew/formula_pin.rb
@@ -0,0 +1,36 @@
+require 'formula'
+require 'fileutils'
+
+class FormulaPin
+  HOMEBREW_PINNED = HOMEBREW_LIBRARY/'PinnedKegs'
+
+  def initialize(formula)
+    @formula = formula
+    @name = formula.name
+    HOMEBREW_PINNED.mkdir unless HOMEBREW_PINNED.exist?
+    @path = HOMEBREW_PINNED/@name
+  end
+
+  def pin_at(version)
+    version_path = @formula.installed_prefix.parent.join(version)
+    FileUtils.ln_s version_path, @path unless pinned? or not version_path.exist?
+  end
+
+  def pin
+    versions = @formula.installed_prefix.parent.children.map { |item| item.basename.to_s }
+    version = versions.map { |item| Version.new(item) }.sort[0].to_s
+    pin_at(version)
+  end
+
+  def unpin
+    FileUtils.rm @path if pinned?
+  end
+
+  def pinned?
+    @path.exist?
+  end
+
+  def pinable?
+    @formula.installed_prefix.parent.children.length > 0
+  end
+end