Deprecate cabal format

cabal-install/src/Distribution/Client/Main.hs

@@ -50,6 +50,7 @@ import Distribution.Client.Setup
   , copyCommand
   , defaultConfigExFlags
   , defaultInstallFlags
+  , dumpPackageDescriptionCommand
   , fetchCommand
   , filterCommonFlags
   , formatCommand
@@ -187,7 +188,8 @@ import Distribution.Client.Errors
 import Distribution.Compat.ResponseFile
 import qualified Distribution.Make as Make
 import Distribution.PackageDescription.PrettyPrint
-  ( writeGenericPackageDescription
+  ( showGenericPackageDescription
+  , writeGenericPackageDescription
   )
 import qualified Distribution.Simple as Simple
 import Distribution.Simple.Build
@@ -433,10 +435,11 @@ mainWorker args = do
       , regularCmd genBoundsCommand genBoundsAction
       , regularCmd CmdOutdated.outdatedCommand CmdOutdated.outdatedAction
       , wrapperCmd hscolourCommand hscolourCommonFlags
-      , hiddenCmd formatCommand formatAction
+      , regularCmd formatCommand formatAction
       , hiddenCmd actAsSetupCommand actAsSetupAction
       , hiddenCmd manpageCommand (manpageAction commandSpecs)
       , regularCmd CmdListBin.listbinCommand CmdListBin.listbinAction
+      , hiddenCmd dumpPackageDescriptionCommand dumpPackageDescriptionAction
       ]
         ++ concat
           [ newCmd CmdConfigure.configureCommand CmdConfigure.configureAction
@@ -1342,6 +1345,7 @@ checkAction checkFlags extraArgs _globalFlags = do
 
 formatAction :: Flag Verbosity -> [String] -> Action
 formatAction verbosityFlag extraArgs _globalFlags = do
+  hPutStrLn stderr "WARNING: `cabal format` is deprecated and will be removed in 3.16"
   let verbosity = fromFlag verbosityFlag
   path <- case extraArgs of
     [] -> relativeSymbolicPath <$> tryFindPackageDesc verbosity Nothing
@@ -1350,6 +1354,15 @@ formatAction verbosityFlag extraArgs _globalFlags = do
   -- Uses 'writeFileAtomic' under the hood.
   writeGenericPackageDescription (getSymbolicPath path) pkgDesc
 
+dumpPackageDescriptionAction :: Flag Verbosity -> [String] -> Action
+dumpPackageDescriptionAction verbosityFlag extraArgs _globalFlags = do
+  let verbosity = fromFlag verbosityFlag
+  path <- case extraArgs of
+    [] -> relativeSymbolicPath <$> tryFindPackageDesc verbosity Nothing
+    (p : _) -> return $ makeSymbolicPath p
+  pkgDesc <- readGenericPackageDescription verbosity Nothing path
+  putStrLn $ showGenericPackageDescription pkgDesc
+
 reportAction :: ReportFlags -> [String] -> Action
 reportAction reportFlags extraArgs globalFlags = do
   let verbosity = fromFlag (reportVerbosity reportFlags)

cabal-install/src/Distribution/Client/Setup.hs

@@ -73,6 +73,7 @@ module Distribution.Client.Setup
   , checkCommand
   , CheckFlags (..)
   , formatCommand
+  , dumpPackageDescriptionCommand
   , uploadCommand
   , UploadFlags (..)
   , IsCandidate (..)
@@ -301,6 +302,7 @@ globalCommand commands =
               , "hscolour"
               , "exec"
               , "path"
+              , "format"
               , "new-build"
               , "new-configure"
               , "new-repl"
@@ -405,6 +407,7 @@ globalCommand commands =
                 , startGroup "deprecated"
                 , addCmd "unpack"
                 , addCmd "hscolour"
+                , addCmd "format"
                 , par
                 , startGroup "new-style projects (forwards-compatible aliases)"
                 , addCmd "v2-build"
@@ -1745,18 +1748,45 @@ cleanCommand =
         "Usage: " ++ pname ++ " v1-clean [FLAGS]\n"
     }
 
+-- If you read this comment after cabal-install 3.16 has already been released,
+-- it seems we forgot to delete the command, which we said we would do for 3.16.
+-- So please: do remove this command.
 formatCommand :: CommandUI (Flag Verbosity)
 formatCommand =
   CommandUI
     { commandName = "format"
-    , commandSynopsis = "Reformat the .cabal file using the standard style."
-    , commandDescription = Nothing
+    , commandSynopsis = "Rewrite the .cabal file using the parsed package description."
+    , commandDescription = Just $ \_ ->
+        wrapText $
+          "cabal-install parses the .cabal file into its internal package description "
+            ++ "datatype. This command rewrites the file with the parsed description.\n"
+            ++ "\n"
+            ++ "Note that the parsed description does not include the comments "
+            ++ "in the original file nor the common stanzas, which are expanded "
+            ++ "during the package description resolution.\n"
+            ++ "\n"
+            ++ "This command is barely a raw formatter. Its functionality has "
+            ++ "been moved to `cabal dump-package-description` which will not "
+            ++ "overwrite the file. In cabal-install 3.16 this command will be "
+            ++ "removed."
     , commandNotes = Nothing
     , commandUsage = usageAlternatives "format" ["[FILE]"]
     , commandDefaultFlags = toFlag normal
     , commandOptions = \_ -> []
     }
 
+dumpPackageDescriptionCommand :: CommandUI (Flag Verbosity)
+dumpPackageDescriptionCommand =
+  CommandUI
+    { commandName = "dump-package-description"
+    , commandSynopsis = "Dump the parsed package description to stdout"
+    , commandDescription = Nothing
+    , commandNotes = Nothing
+    , commandUsage = usageAlternatives "dump-package-description" ["[FILE]"]
+    , commandDefaultFlags = toFlag normal
+    , commandOptions = \_ -> []
+    }
+
 manpageCommand :: CommandUI ManpageFlags
 manpageCommand =
   CommandUI

changelog.d/pr-10469

@@ -0,0 +1,10 @@
+synopsis: Deprecate `cabal format`
+packages: cabal-install
+prs: #10469
+significance:
+
+description: {
+
+- Deprecate `cabal format` in favor of `cabal dump-package-description` which is still a hidden, internal command.
+
+}