Merge pull request #1177 from scpeters/man_exit_code

Man exit code

Library/Homebrew/dev-cmd/man.rb

-#:  * `man`:
+#:  * `man` [`--fail-if-changed`]:
 #:    Generate Homebrew's manpages.
+#:
+#:    If `--fail-if-changed` is passed, the command will return a failing
+#:    status code if changes are detected in the manpage outputs.
+#:    This can be used for CI to be notified when the manpages are out of date.
 
 require "formula"
 require "erb"
@@ -18,6 +22,12 @@ module Homebrew
     else
       regenerate_man_pages
     end
+
+    if system "git", "-C", HOMEBREW_REPOSITORY, "diff", "--quiet", "docs/brew.1.html", "manpages"
+      puts "No changes to manpage output detected."
+    elsif ARGV.include?("--fail-if-changed")
+      Homebrew.failed = true
+    end
   end
 
   private

docs/brew.1.html

@@ -467,7 +467,8 @@ for instance, for implementing pre-commit hooks.</p></dd>
 <dt><code>bump-formula-pr</code> [<code>--devel</code>] [<code>--dry-run</code>] [<code>--audit</code>|<code>--strict</code>] <code>--tag=</code><var>tag</var> <code>--revision=</code><var>revision</var> <var>formula</var></dt><dd><p>Creates a pull request to update the formula with a new url or a new tag.</p>
 
 <p>If a <var>url</var> is specified, the <var>sha-256</var> checksum of the new download must
-also be specified.</p>
+also be specified. A best effort to determine the <var>sha-256</var> and <var>formula</var>
+name will be made if either or both values are not supplied by the user.</p>
 
 <p>If a <var>tag</var> is specified, the git commit <var>revision</var> corresponding to that
 tag must also be specified.</p>
@@ -477,10 +478,19 @@ The development spec must already exist.</p>
 
 <p>If <code>--dry-run</code> is passed, print what would be done rather than doing it.</p>
 
+<p>If <code>--write</code> is passed along with <code>--dry-run</code>, perform a not-so-dry run
+making the expected file modifications but not taking any git actions.</p>
+
 <p>If <code>--audit</code> is passed, run <code>brew audit</code> before opening the PR.</p>
 
 <p>If <code>--strict</code> is passed, run <code>brew audit --strict</code> before opening the PR.</p>
 
+<p>If <code>--mirror=</code><var>url</var> is passed, use the value as a mirror url.</p>
+
+<p>If <code>--version=</code><var>version</var> is passed, use the value to override the value
+parsed from the url or tag. Note that <code>--version=0</code> can be used to delete
+an existing <code>version</code> override from a formula if it has become redundant.</p>
+
 <p>Note that this command cannot be used to transition a formula from a
 url-and-sha256 style specification into a tag-and-revision style
 specification, nor vice versa. It must use whichever style specification
@@ -515,7 +525,11 @@ non-zero exit code if any missing libraries were found.</p>
 
 <p>If <code>--reverse</code> is passed, print the dylib followed by the binaries
 which link to it for each library the keg references.</p></dd>
-<dt class="flush"><code>man</code></dt><dd><p>Generate Homebrew's manpages.</p></dd>
+<dt><code>man</code> [<code>--fail-if-changed</code>]</dt><dd><p>Generate Homebrew's manpages.</p>
+
+<p>If <code>--fail-if-changed</code> is passed, the command will return a failing
+status code if changes are detected in the manpage outputs.
+This can be used for CI to be notified when the manpages are out of date.</p></dd>
 </dl>
 
 

manpages/brew.1

@@ -656,7 +656,7 @@ Generate a bottle (binary package) from a formula installed with \fB\-\-build\-b
 Creates a pull request to update the formula with a new url or a new tag\.
 .
 .IP
-If a \fIurl\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\.
+If a \fIurl\fR is specified, the \fIsha\-256\fR checksum of the new download must also be specified\. A best effort to determine the \fIsha\-256\fR and \fIformula\fR name will be made if either or both values are not supplied by the user\.
 .
 .IP
 If a \fItag\fR is specified, the git commit \fIrevision\fR corresponding to that tag must also be specified\.
@@ -668,12 +668,21 @@ If \fB\-\-devel\fR is passed, bump the development rather than stable version\.
 If \fB\-\-dry\-run\fR is passed, print what would be done rather than doing it\.
 .
 .IP
+If \fB\-\-write\fR is passed along with \fB\-\-dry\-run\fR, perform a not\-so\-dry run making the expected file modifications but not taking any git actions\.
+.
+.IP
 If \fB\-\-audit\fR is passed, run \fBbrew audit\fR before opening the PR\.
 .
 .IP
 If \fB\-\-strict\fR is passed, run \fBbrew audit \-\-strict\fR before opening the PR\.
 .
 .IP
+If \fB\-\-mirror=\fR\fIurl\fR is passed, use the value as a mirror url\.
+.
+.IP
+If \fB\-\-version=\fR\fIversion\fR is passed, use the value to override the value parsed from the url or tag\. Note that \fB\-\-version=0\fR can be used to delete an existing \fBversion\fR override from a formula if it has become redundant\.
+.
+.IP
 Note that this command cannot be used to transition a formula from a url\-and\-sha256 style specification into a tag\-and\-revision style specification, nor vice versa\. It must use whichever style specification the preexisting formula already uses\.
 .
 .TP
@@ -717,9 +726,12 @@ If \fB\-\-test\fR is passed, only display missing libraries and exit with a non\
 If \fB\-\-reverse\fR is passed, print the dylib followed by the binaries which link to it for each library the keg references\.
 .
 .TP
-\fBman\fR
+\fBman\fR [\fB\-\-fail\-if\-changed\fR]
 Generate Homebrew\'s manpages\.
 .
+.IP
+If \fB\-\-fail\-if\-changed\fR is passed, the command will return a failing status code if changes are detected in the manpage outputs\. This can be used for CI to be notified when the manpages are out of date\.
+.
 .P
 \fBpull\fR [\fB\-\-bottle\fR] [\fB\-\-bump\fR] [\fB\-\-clean\fR] [\fB\-\-ignore\-whitespace\fR] [\fB\-\-resolve\fR] [\fB\-\-branch\-okay\fR] [\fB\-\-no\-pbcopy\fR] [\fB\-\-no\-publish\fR] \fIpatch\-source\fR [\fIpatch\-source\fR]
 .