git-filter-repo.txt: document mapping output

Useful commit and reference mappings are created on every run. These are
helpful in a number of situations, and should be documented so that
end-users and Git hosts can understand how to use the output.

The commit-map is particularly useful for Git hosts to override
retention mechanisms, like hidden refs. This allows end-users to purge
large files and sensitive data.

Signed-off-by: James Ramsay <[email protected]>

Author: jamesramsay

Documentation/git-filter-repo.txt

@@ -332,6 +332,38 @@ Miscellaneous options
 --quiet::
 	Pass --quiet to other git commands called.
 
+OUTPUT
+------
+
+Every time filter-repo is run, files are created in the `.git/filter-repo/`
+directory. These files overwritten unconditionally on every run.
+
+Commit map
+~~~~~~~~~~
+
+The `.git/filter-repo/commit-map` file contains a mapping of how all
+commits were (or were not) changed.
+
+  * A header is the first line with the text "old" and "new"
+  * Commit mappings are in no particular order
+  * All commits in range of the rewrite will be listed, even commits
+    that are unchanged (e.g. because the commit pre-dated when the
+    large file(s) were introduced to the repo).
+  * An all-zeros hash, or null SHA, represents a non-existant object.
+    When in the "new" column, this means the commit was removed
+    entirely.
+
+Reference map
+~~~~~~~~~~~~~
+
+The `.git/filter-repo/ref-map` file contains a mapping of which local
+references were changed.
+
+  * A header is the first line with the text "old" and "new"
+  * Reference mappings are in no particular order
+  * An all-zeros hash, or null SHA, represents a non-existant object.
+    When in the "new" column, this means the ref was removed entirely.
+
 [[FRESHCLONE]]
 FRESH CLONE SAFETY CHECK AND --FORCE
 ------------------------------------