# HG changeset patch
# User Matt Harbison <matt_harbison@yahoo.com>
# Date 2023-04-25 21:49:35
# Node ID f4ff55583dec039eb7acdee7ac8ee57495770384
# Parent  4ca794f4e6a3043774090f7d91807eb89dc425fb

fix: highlight the required configuration and behavior of the fixer tools

The problem is that `hg help fix` didn't mention *how* to configure the tools,
and while I knew that `{rootpath}` existed in the configuration, I missed that
the tools require reading content from stdin.  (I configured `gofmt` to use
`{rootpath}`, and that had the effect of squashing all changes in a file at `.`
into the first commit and emptying that content from its descendants.)

Basically all this does is put a pointer in the default (command level) help to
the extension level help that mentions the configuration, and moves the
extension level help that documents reading from stdin and writing to stdout to
the top to give it more prominence.  The last sentence is adjusted a bit to
reflect the new location.

diff --git a/hgext/fix.py b/hgext/fix.py
--- a/hgext/fix.py
+++ b/hgext/fix.py
@@ -9,6 +9,13 @@
 Provides a command that runs configured tools on the contents of modified files,
 writing back any fixes to the working copy or replacing changesets.
 
+Fixer tools are run in the repository's root directory. This allows them to read
+configuration files from the working copy, or even write to the working copy.
+The working copy is not updated to match the revision being fixed. In fact,
+several revisions may be fixed in parallel. Writes to the working copy are not
+amended into the revision being fixed; fixer tools MUST always read content to
+be fixed from stdin, and write fixed file content back to stdout.
+
 Here is an example configuration that causes :hg:`fix` to apply automatic
 formatting fixes to modified lines in C++ code::
 
@@ -113,13 +120,6 @@ perform other post-fixing work. The supp
     mapping fixer tool names to lists of metadata values returned from
     executions that modified a file. This aggregates the same metadata
     previously passed to the "postfixfile" hook.
-
-Fixer tools are run in the repository's root directory. This allows them to read
-configuration files from the working copy, or even write to the working copy.
-The working copy is not updated to match the revision being fixed. In fact,
-several revisions may be fixed in parallel. Writes to the working copy are not
-amended into the revision being fixed; fixer tools should always write fixed
-file content back to stdout as documented above.
 """
 
 
@@ -239,7 +239,8 @@ usage = _(b'[OPTION]... [FILE]...')
 def fix(ui, repo, *pats, **opts):
     """rewrite file content in changesets or working directory
 
-    Runs any configured tools to fix the content of files. Only affects files
+    Runs any configured tools to fix the content of files. (See
+    :hg:`help -e fix` for details about configuring tools.) Only affects files
     with changes, unless file arguments are provided. Only affects changed lines
     of files, unless the --whole flag is used. Some tools may always affect the
     whole file regardless of --whole.
diff --git a/tests/test-fix.t b/tests/test-fix.t
--- a/tests/test-fix.t
+++ b/tests/test-fix.t
@@ -84,10 +84,11 @@ Help text for fix.
   
   rewrite file content in changesets or working directory
   
-      Runs any configured tools to fix the content of files. Only affects files
-      with changes, unless file arguments are provided. Only affects changed
-      lines of files, unless the --whole flag is used. Some tools may always
-      affect the whole file regardless of --whole.
+      Runs any configured tools to fix the content of files. (See 'hg help -e
+      fix' for details about configuring tools.) Only affects files with
+      changes, unless file arguments are provided. Only affects changed lines of
+      files, unless the --whole flag is used. Some tools may always affect the
+      whole file regardless of --whole.
   
       If --working-dir is used, files with uncommitted changes in the working
       copy will be fixed. Note that no backup are made.
@@ -125,6 +126,13 @@ Help text for fix.
   Provides a command that runs configured tools on the contents of modified
   files, writing back any fixes to the working copy or replacing changesets.
   
+  Fixer tools are run in the repository's root directory. This allows them to
+  read configuration files from the working copy, or even write to the working
+  copy. The working copy is not updated to match the revision being fixed. In
+  fact, several revisions may be fixed in parallel. Writes to the working copy
+  are not amended into the revision being fixed; fixer tools MUST always read
+  content to be fixed from stdin, and write fixed file content back to stdout.
+  
   Here is an example configuration that causes 'hg fix' to apply automatic
   formatting fixes to modified lines in C++ code:
   
@@ -231,13 +239,6 @@ Help text for fix.
       executions that modified a file. This aggregates the same metadata
       previously passed to the "postfixfile" hook.
   
-  Fixer tools are run in the repository's root directory. This allows them to
-  read configuration files from the working copy, or even write to the working
-  copy. The working copy is not updated to match the revision being fixed. In
-  fact, several revisions may be fixed in parallel. Writes to the working copy
-  are not amended into the revision being fixed; fixer tools should always write
-  fixed file content back to stdout as documented above.
-  
   list of commands:
   
    fix           rewrite file content in changesets or working directory