Adding Pre-upload instructions to checkstyle README
am: 153a9a100e
Change-Id: If9716b10d8c6c1b682742ef12be971f5974cc96d
diff --git a/README b/README
deleted file mode 100644
index d147f8b..0000000
--- a/README
+++ /dev/null
@@ -1,28 +0,0 @@
-Description:
-Checkstyle is used by developers to validate Java code style before running repo upload.
-
-It can be invoked in two ways.
-1. To check style of entire specific files:
-checkstyle.py -f FILE [FILE ...]
-2. To check style of the lines modified in the latest commit:
-checkstyle.py
-
-Projects used:
-* Name: Checkstyle
- Description: Checkstyle is a development tool to help programmers write Java code that
- adheres to a coding standard.
- URL: http://checkstyle.sourceforge.net/
- Version: 7.4-SNAPSHOT
- License: LGPL 2.1
- License File: LICENSE
- Source git repo: https://android.googlesource.com/platform/external/checkstyle
-
-* Name: Git-Lint
- Description: Git-lint is a tool to run lint checks on only files changed in
- the latest commit.
- URL: https://github.com/sk-/git-lint/
- Version: 0.0.8
- License: Apache 2.0
- License File: gitlint/LICENSE
- Local Modifications:
- - Downloaded gitlint/git.py and git/utils.py files individually.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7888a4f
--- /dev/null
+++ b/README.md
@@ -0,0 +1,66 @@
+# Checkstyle
+
+Checkstyle is used by developers to validate Java code style and formatting,
+and can be run as part of the pre-upload hooks.
+
+[TOC]
+
+## Running it
+
+It can be invoked in two ways.
+1. To check style of entire specific files:
+ `checkstyle.py -f FILE [FILE ...]`
+2. To check style of the lines modified in the latest commit:
+ `checkstyle.py`
+
+
+## Projects used
+
+### Checkstyle
+
+A development tool to help programmers write Java code that adheres to a
+coding standard.
+
+* URL: https://checkstyle.sourceforge.io/
+* Version: 7.4-SNAPSHOT
+* License: LGPL 2.1
+* License File: LICENSE
+* Source repo: https://android.googlesource.com/platform/external/checkstyle
+
+### Git-Lint
+
+Git-lint is a tool to run lint checks on only files changed in the latest
+commit.
+
+* URL: https://github.com/sk-/git-lint/
+* Version: 0.0.8
+* License: Apache 2.0
+* License File: gitlint/LICENSE
+* Local Modifications:
+ * Downloaded gitlint/git.py and git/utils.py files individually.
+
+## Pre-upload linting
+
+To run checkstyle as part of the pre-upload hooks, add the following line to
+your `PREUPLOAD.cfg`:
+```
+checkstyle_hook = ${REPO_ROOT}/prebuilts/checkstyle/checkstyle.py --sha ${PREUPLOAD_COMMIT}
+```
+
+Note that checkstyle does not always agree with clang-format, and so it's best
+to only have one enabled for Java.
+
+### Disabling Clang Format for Java
+
+In `.clang-format` add the following to disable format checking and correcting
+for Java:
+```
+---
+Language: Java
+DisableFormat: true
+SortIncludes: false
+---
+```
+In some versions of clang-format, `DisableFormat` doesn't stop the sorting of
+includes. So to fully disable clang-format from doing anything for Java files,
+both options are needed.
