diff --git a/v3-to-v4.md b/v3-to-v4.md
index e4b9098f3..0a931f2f9 100644
--- a/v3-to-v4.md
+++ b/v3-to-v4.md
@@ -64,6 +64,26 @@ and try to set `--ref` from them.
     |   other  |  other  |   ""    | error                        |
     |----------|---------|---------|------------------------------|
 
+#### Default target
+
+In git-sync v3, if neither `--branch` nor `--rev` were specified, the default
+was to sync the HEAD of the branch named "master".  Many git repos have changed
+to "main" or something else as the default branch name, so git-sync v4 changes
+the default target to be the HEAD of whatever the `--repo`'s default branch is.
+If that default branch is not "master", then the default target will be
+different in v4 than in v3.
+
+#### Abbreviated hashes
+
+Because of the fetch loop, git-sync v3 allowed a user to specify `--branch` and
+`--rev`, where the rev was a shortened hash (aka SHA), which would be locally
+expanded to the full hash.  v4 tries hard not to pull extra stuff, which means
+we don't have enough information locally to do that resolution, and there no
+way to ask the server to do it for us (at least, not as far as we know).
+
+The net result is that, when using a hash for `--ref`, it must be a full hash,
+and not an abbreviated form.
+
 ### Log-related flags
 
 git-sync v3 exposed a number of log-related flags (e.g. `-logtostderr`).  These