Troubleshooting

Audience

Anyone committing changes to the SOTER project who hits a failing pre-commit hook or a confusing git commit outcome.

Goal

Diagnose and resolve the most common git/pre-commit failures without needing to ask for help, and know when it is safe to bypass the checks.

Prerequisites

• pre-commit installed and configured for this repository. It automatically checks code quality (linter, formatting) before every git commit; if the checks fail, the commit is aborted.
• A working git checkout with the changes you intend to commit.

Workflow

1. Attempt the commit as usual.
2. If it fails, read which hook failed (trailing-whitespace, markdownlint, ruff, black, ...).
3. When in doubt, run all hooks proactively instead of reacting to one failure at a time (see the golden command below).
4. Stage whatever the auto-fixers changed, fix anything that requires a manual decision, and commit again.

Commands

Run all hooks on all files to see everything that would fail, in one pass:

pre-commit run --all-files

Run only markdownlint with a diff of what it would change:

pre-commit run markdownlint --all-files --show-diff-on-failure

Re-stage auto-fixed files and retry the commit:

git add .
git commit -m "Your message"

Check ruff manually before committing, and apply its safe auto-fixes:

ruff check .
ruff check --fix .

Force a commit past the hooks (not recommended — CI will still fail):

git commit -m "Message" --no-verify

Expected Result

• pre-commit run --all-files reports no failures, or only failures you have consciously fixed.
• git commit succeeds without --no-verify.
• No unstaged changes remain after committing (git status is clean).

Troubleshooting

trim trailing whitespace error

Symptoms:

trim trailing whitespace.................................................Failed
- hook id: trailing-whitespace

Cause:

• Your code or documentation contains spaces or tabs at the very end of lines. The hook automatically removes them, modifying the file after you attempted to commit it.

Fix:

• Stage the changes made by the auto-fixer and commit again:

bash git add . git commit -m "Your message"

markdownlint error (errors in .md documentation)

Symptoms:

markdownlint.............................................................Failed
- hook id: markdownlint

Cause — most common:

• Missing a blank line at the end of the file.
• Poor table formatting (missing spaces next to pipe characters |).
• Too many blank lines in a row.

Fix:

1. Run the auto-fixer — many markdownlint issues do not need to be corrected manually:

bash pre-commit run markdownlint --all-files --show-diff-on-failure

1. If the errors are corrected automatically, git add . and commit again.
2. If the errors are structural or logical (for example, incorrect header hierarchy), the tool reports the line number — fix it manually in your editor.

General failures — golden command

Instead of fighting every error one by one during committing, run all the checks at once:

pre-commit run --all-files

Cause:

• Any hook that has an auto-fixer may report Failed the first time simply because it just applied fixes.

Fix:

• If git status shows unstaged changes after running the command above, the auto-fixer already did the work for you:

bash git add . git commit -m "Your message"

"Stashed changes conflicted..." (worst case)

Symptoms:

[WARNING] Stashed changes conflicted with hook auto-fixes... Rolling back
fixes...

Cause:

• The auto-fixer tried to correct something in the same place you were modifying, resulting in a conflict with pre-commit's internal stash.

Fix:

1. Run git status to check what changed.
2. Run pre-commit run --all-files before adding files to the stage.
3. Manually inspect the files, add them, and commit.

Simultaneous ruff + black errors (linter + formatter)

Symptoms:

ruff.....................................................................Failed
- hook id: ruff
- exit code: 1

backend/schemas/factories.py:179:5: F841 Local variable `pl_label` is assigned
to but never used

black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted backend/schemas/factories.py
reformatted backend/config/urls.py
...
7 files reformatted, 5 files left unchanged.

The commit is aborted, with two separate errors shown.

Cause:

• There are two independent issues in a single commit: ruff (a logical error, such as unused variable F841, which the auto-fixer does not correct — it requires a manual fix) and black (a formatting issue, where the reformatting has already been applied to the files).

Fix:

1. Manually fix the error reported by ruff (in this example, remove or use the variable pl_label in factories.py:179).
2. Stage all fixes — your manual ones plus the automatic ones from black:

bash git add .

1. Commit again:

bash git commit -m "Your message"

Tip: run ruff manually before committing to see the list of errors, and apply its safe auto-fixes:

ruff check .
ruff check --fix .

Errors marked as --unsafe-fixes (like F841) require a manual decision, since removing a variable might alter program logic.

Forcing a commit past the hooks

If you need to force-commit something (not recommended!), you can use the --no-verify flag, but the errors will still fail CI: git commit -m "Message" --no-verify

Related Documents

• DocumentationStyleGuide.md - writing profile and document-type rules.
• GuideTemplate.md - guide document template.
• ManualsIndex.md - guide and manual index.
• Quickstart.md - first-run guide that links here for commit-time errors.
• PyreflyLinterSetup.md - the ruff → pytest → pyrefly quality pipeline referenced here.
• ArchitectureOverview.md - technical architecture context.