Merge pull request #16 from JBEI/pre-commit

Update pre-commit documentation

Advanced.md

@@ -0,0 +1,44 @@
+# Advanced pre-commit commands
+
+This document contains example commands for advanced use in a `pre-commit` workflow as
+configured in this repo. Refer to `pre-commit` or to other tool-specific documentation for more
+information.
+
+Run any `pre-commit` hook against a specific file (for example `flake8`) :
+
+ pre-commit run [hook] --file myfile.py
+
+Run all `pre-commit` hooks against a specific file:
+
+ pre-commit run --file myfile.py
+
+Run a specific `pre-commit` hook (e.g. `flake8`) against all files in the repo:
+
+ pre-commit run [hook] --all-files
+
+## Ignoring pre-commit hooks
+
+Ignoring code quality feedback is highly discouraged, but sometimes necessary, e.g. when code
+quality tools disagree.
+
+In such cases, first try updating the tools:
+
+1. Stash your code changes by running `git stash`
+2. Update the tool versions by running `pre-commit autoupdate`
+3. Re-run updated tools on the whole repo
+
+ `pre-commit run --all-files`
+
+4. Resolve and commit all required code changes.
+5. Unstash your changes.
+
+ `git stash pop`
+
+6. Re-try your original commit.
+
+ `git commit`
+
+As a last resort, first resolve all addressable feedback on your changes, and then commit, ignoring
+only the subset of feedback that can't be resolved.
+
+ git commit --no-verify

README.md

@@ -63,42 +63,40 @@ and one that fails, *FailingDemoRepoNotebook.ipynb*.
 
 ## Pre-commit
 
-Setting up pre-commit is fairly straightforward. This repo includes a _.pre-commit-config.yaml_ file
-which sets up the hooks for tools that are run before a commit can complete. These tools help
-standardize formatting and clean up code (e.g. remove unused imports) before it is submitted.
+This repo includes a _.pre-commit-config.yaml_ file which sets up the hooks to run tools before a
+commit can complete. These tools help standardize formatting and clean up code
+(e.g. remove unused imports) before it is submitted. 
 
 To install pre-commit in your env, run:
 
 ```pip install pre-commit```
 
-You can then install the pre-commit script in git by running:
+You can then install the pre-commit script in your local repo by running:
 
 ```pre-commit install```
 
 If you have a _.pre-commit-config.yaml_ file in your repo, you will notice differences in your next commit.
 The tools specified in _.pre-commit-config.yaml_ will run and will block the commit if any
 errors are found. It may be helpful to run the tools directly when you are trying to fix these errors.
 
-For the python tools _black_ and _flake8_, install the tools with:
+### Running Black and Flake8
 
-```
-pip install black
-pip install flake8
-```
+For the Python tools _black_ and _flake8_, pre-commit will install and run the tools for you.
 
 If you have errors in say _myfile.py_, you can fix the formatting errors with:
 
-```black myfile.py```
+```pre-commit run black --file myfile.py```
 
 Don't forget to add the changes to the staged area before you retry your commit.
 
-For _flake8_ errors, you can list them by running _flake8_ directly, but you 
+For _flake8_ errors, you can list them by running _flake8_ directly, but you
 may have to make fixes by hand.
 
-```flake8 myfile.py```
+```pre-commit run flake8 --file myfile.py```
 
-Note that there are some helpful tips on using pre-commit in different ways on
-the [ART Install page](https://github.com/JBEI/AutomatedRecommendationTool/blob/master/docs/Installing.md).
+### Advanced use
+
+See [Advanced.md][Advanced.md] for examples that may be helpful for advanced use.
 
 ## Automated Documentation