Format: add some formatting aliases, improve dev docs

The aliases are easier than calling check_coding.sh manually,
and we already provide an alias file for the fixes alias, so
do the same for these.

(cherry picked from commit 241127788e)

Documentation/development/coding-style-policy.md

@@ -76,26 +76,38 @@ to "true" for the KiCad repo:
     git config kicad.check-format true
 
 Without this config, the format checker will not run on commit, but you can
-still check files staged for commit manually:
+still check files staged for commit manually (see below).
-
-    tools/check_coding.sh --diff
 
 If the hook is enabled, when you commit a change, you will be told if you
-have caused any style violations (only in your changed code). You can fix your
+have caused any style violations (only in your changed code). You can then fix
-staged changes automatically with this tool:
+the errors, either manually, or with the tools below.
 
-    tools/check_coding.sh
+If you are warned about formatting errors, but you are sure your style is correct,
-
+you can still commit:
-Or you can proceed anyway, if you are sure your style is correct:
 
     git commit --no-verify
 
-The `check_coding.sh` tool has other modes:
+### Correcting Formatting Errors ## {#correcting-formatting-errors}
 
-* Make (or see only) changes to files modified in the previous commit:
+There is a Git aliases file that provides the right commands to show and correct
+formatting errors. Add to your repository config by running this command from
+the source directory:
+
+    git config --add include.path $(pwd)/helpers/git/format_alias
+
+Then you can use the following aliases:
+
+* `git check-format`: show any formatting warnings (but make no changes)
+* `git fix-format`: correct formatting (you will need to `git add` afterwards)
+
+These aliases use a script, `tools/check-coding.sh`, which takes care of only
+checking the formatting for files that should be formatted. This script has
+other uses:
+
+* Make (or see only) violations in files modified in the previous commit (useful
+when interactive-rebasing):
     * `check_coding.sh --amend [--diff]`
 
-
 # 2. Naming Conventions # {#naming_conventions}
 Before delving into anything as esoteric as indentation and formatting,
 naming conventions need to be addressed. This section does not attempt

helpers/git/format_alias

@@ -0,0 +1,10 @@
+[alias]
+	# Alias to check the formatting since the last commit and show the issues
+	# that are found. No files will be changed. Only lines changed since the
+	# last commit are considered (and only for files that should be reformatted)
+	check-format = "! f() { tools/check_coding.sh --diff; }; f"
+
+	# Alias to check and fix formatting issues in files changed since the last
+	# commit. Only lines changed since the last commit are considered (and only
+	# for files that should be reformatted)
+	fix-format = "! f() { tools/check_coding.sh; }; f"

tools/check_coding.sh

@@ -30,7 +30,7 @@ usage='usage: check_coding.sh [<options>] [--]
 
      --diff                     Only show proposed changes, do not format files
 
-     --cached                   Re-format changes currently staged for commit
+     --cached                   Re-format changes currently staged for commit (default)
      --amend                    Re-format changes made in the previous commit
 '