From 603d7e38226d352911eceeab4da1923650e643f6 Mon Sep 17 00:00:00 2001
From: Daniel Baumann <daniel.baumann@progress-linux.org>
Date: Sat, 4 May 2024 03:05:28 +0200
Subject: Merging upstream version 0.1.30.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
---
 debputy.pod | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 57 insertions(+), 1 deletion(-)

(limited to 'debputy.pod')

diff --git a/debputy.pod b/debputy.pod
index 933b6d0..0cee740 100644
--- a/debputy.pod
+++ b/debputy.pod
@@ -14,7 +14,9 @@ B<debputy> B<check-manifest> [B<--debputy-manifest=>I<path/to/debputy.manifest>]
 
 B<debputy> B<annotate-packaging-files>
 
-B<debputy> B<lint>
+B<debputy> B<lint> [--auto-fix]
+
+B<debputy> B<reformat> [--no-auto-fix]
 
 B<debputy> B<lsp> B<editor-config> B<NAME>
 
@@ -117,6 +119,60 @@ The B<--no-act> is an alias of B<--no-apply-changes> to match the name that B<de
 
 =back
 
+=item reformat
+
+I<< Note: This subcommand needs optional dependencies to work from B<Recommends> or B<Suggests> >>
+
+Apply the formatting style on the packaging files.
+
+This is the same style that B<debputy lsp server> would have applied if requested to reformat the files.
+
+The B<debputy> tool reacts to having a B<X-Style> field in F<debian/control> from where you can pick
+a named style. The recommended style is B<black>, which is named such to match the B<black> code formatter
+for B<Python> (which imposes a style that evolves over time).
+
+For packages that does not have the B<X-Style> field, B<debputy> will result to looking up the maintainer
+(and possibly co-maintainers) for known style preferences in its built-in configuration. If B<debputy>
+can derive a style that all parties would agree too (or the team style for packaging teams), then that
+style will be used.
+
+At the time of introduction, the B<black> style is similar to that of B<wrap-and-sort -astkb>, since
+that was one of the most common style according to L<https://bugs.debian.org/895570>, But the style is
+expected to evolve over time and the two styles may diverge over time.
+
+The command accepts the following options:
+
+=over 4
+
+=item B<--style=black>
+
+Override the package style and use the B<black> style. Any auto-detection or B<X-Style> setting will
+be ignored.
+
+=item B<--auto-fix>, B<--no-auto-fix>
+
+Decide whether any changes should be fixed automatically.
+
+Either way, a difference (B<diff -u>) is displayed to stdout if any changes were detected.
+
+=item B<--linter-exit-code>, B<--no-linter-exit-code>
+
+There is a convention among linter tools to return a non-zero exit code for "issues".  The
+B<--linter-exit-code> will enforce this behaviour while the B<--no-linter-exit-code> will disable
+it.
+
+The B<debputy> program will use exit code B<2> for "issues" as a "linter exit code" when
+linting based exit codes are active.
+
+Not having a linter based exit code can be useful if you want to run the tool programmatically
+to perform the action and you only want the exit code to tell whether there was a problem
+providing the results.
+
+If you rely on the exit code, you are recommended to explicitly pass the relevant variant of the
+flag even if the current default matches your wishes.
+
+=back
+
 =item lint
 
 I<< Note: This subcommand needs optional dependencies to work from B<Recommends> or B<Suggests> >>
-- 
cgit v1.2.3