Documentation for the 'outdated' command.

Cabal/doc/developing-packages.rst

@@ -1147,6 +1147,57 @@ For example, given the following dependencies specified in
       foo >= 0.5.2 && < 0.6
       bar >= 1.1 && < 1.2
 
+Listing outdated dependency version bounds
+""""""""""""""""""""""""""""""""""""""""""
+
+Manually updating dependency version bounds in a ``.cabal`` file or a
+freeze file can be tedious, especially when there's a lot of
+dependencies. The ``cabal outdated`` command is designed to help with
+that. It will print a list of packages for which there is a new
+version on Hackage that is outside the version bound specified in the
+``build-depends`` field. The ``outdated`` command can also be
+configured to act on the freeze file (both old- and new-style) and
+ignore major (or all) version bumps on Hackage for a subset of
+dependencies.
+
+Example:
+
+.. code-block:: console
+
+    $ cabal outdated
+    Outdated dependencies: HTTP ==4000.3.3 (latest: 4000.3.4), HUnit ==1.3.1.1
+    (latest: 1.5.0.0), ListLike ==4.2.1 (latest: 4.5), QuickCheck ==2.8.2 (latest:
+    2.9.2), aeson ==0.11.2.0 (latest: 1.1.0.0)
+
+    $ cabal outdated --ignore=HTTP
+    Outdated dependencies: HUnit ==1.3.1.1 (latest: 1.5.0.0),
+    ListLike ==4.2.1 (latest: 4.5), QuickCheck ==2.8.2 (latest:
+    2.9.2), aeson ==0.11.2.0 (latest: 1.1.0.0)
+
+    $ cabal outdated --ignore=HTTP --minor=HUnit,ListLike
+    Outdated dependencies: HUnit ==1.3.1.1 (latest: 1.3.1.2),
+    QuickCheck ==2.8.2 (latest: 2.9.2), aeson ==0.11.2.0 (latest: 1.1.0.0)
+
+The following flags are supported by the ``outdated`` command:
+
+``--freeze-file``
+    Read dependency version bounds from the freeze file (``cabal.config``)
+    instead of the package description file (``$PACKAGENAME.cabal``).
+``--new-freeze-file``
+    Read dependency version bounds from the new-style freeze file
+    (``cabal.project.freeze``) instead of the package description file.
+``--exit-code``
+    Exit with a non-zero exit code when there are outdated dependencies.
+``--ignore`` *PACKAGENAMES*
+    Don't warn about outdated dependency version bounds for the packages in this
+    list.
+``--minor`` *PACKAGENAMES*
+    Ignore major version bumps for these packages. E.g. if there's a version 2.0 of
+    a package ``pkg`` on Hackage and the freeze file specifies the constraint
+    ``pkg == 1.9``, ``cabal outdated --freeze --minor=pkg`` will only consider
+    the ``pkg`` outdated when there's a version of ``pkg`` on Hackage satisfying
+    ``pkg > 1.9 && < 2.0``.
+
 Executables
 ^^^^^^^^^^^