Clarify documentation of --diff and --diff-methods (#2680)

* Clarify documentation of --diff and --diff-methods

* Save Psalm cache in CircleCI

.circleci/config.yml

@@ -18,14 +18,21 @@ jobs:
             - composer-v2-{{ checksum "/tmp/cachekey" }}
             # fallback to using the latest cache if no exact match is found (See https://circleci.com/docs/2.0/caching/)
             - composer-v2-
+      - restore_cache:
+          keys:
+            - psalm-cache-{{ checksum "/tmp/cachekey" }} # speeds up run with --diff and --diff-methods
       - run: composer update
       - save_cache:
           key: composer-v2-{{ checksum "/tmp/cachekey" }}
           paths:
             - vendor
+      - save_cache:
+          key: psalm-cache-{{ checksum "/tmp/cachekey" }}
+          paths:
+            - /tmp/psalm
       - run:
           name: Static analysis
-          command: php -dextension=pcntl.so ./psalm --threads=10
+          command: php -dextension=pcntl.so ./psalm --threads=10 --diff --diff-methods
       - persist_to_workspace:
           root: /home/docker/project/
           paths:

docs/running_psalm/command_line_usage.md

@@ -29,7 +29,11 @@ Currently, Shepherd tracks type coverage (the percentage of types Psalm can infe
 Psalm has a couple of command-line options that will result in faster builds:
 
 - `--threads=[n]` to run Psalm’s analysis in a number of threads
-- `--diff` which only checks files you’ve updated (and their dependents).
-- `--diff-methods` which remembers Psalm’s output when scanning particular methods.
+- `--diff` which only checks files you’ve updated since the last run (and their dependents).
+- `--diff-methods` which only checks methods you’ve updated since the last run (and their dependents).
+
+Data from the last run is stored in the *cache directory*, which may be set in [configuration](./configuration.md).
+If you are running Psalm on a build server, you may want to configure the server to ensure that the cache directory
+is preserved between runs.
 
 Running them together (e.g. `--threads=8 --diff --diff-methods`) will result in the fastest possible Psalm run.

src/command_functions.php

@@ -284,10 +284,10 @@ Basic configuration:
         If greater than one, Psalm will run analysis on multiple threads, speeding things up.
 
     --diff
-        Runs Psalm in diff mode, only checking files that have changed (and their dependents)
+        Runs Psalm in diff mode, only checking files that have changed since last run (and their dependents)
 
     --diff-methods
-        Only checks methods that have changed (and their dependents)
+        Only checks methods that have changed since last run (and their dependents)
 
 Surfacing issues:
     --show-info[=BOOLEAN]