commit 2b6826ba4126532b017434e71e02ad55f62c1a12
from: Stefan Sperling <stsp@stsp.name>
date: Mon Feb 24 22:04:15 2020 UTC

attempt to more clearly explain what 'got rebase' is used for

commit - 7ef62c4e3e891c47d0449ca61fcb3fa35a98ec51
commit + 2b6826ba4126532b017434e71e02ad55f62c1a12
blob - 97deeedc9651bb3ad1a7a5765d7e0b80c0b45c0d
blob + 62c5d240f167f230a11d8eeaa5d9300c14c62abb
--- got/got.1
+++ got/got.1
@@ -936,6 +936,21 @@ of the specified
 .Ar branch
 has been rebased.
 .Pp
+When
+.Cm got rebase
+is used as intended, the specified
+.Ar branch
+contains changes made in local commits that are not yet visible in any
+other repositories.
+The work tree's current branch, which must be set with
+.Cm got update -b
+before starting the
+.Cm rebase
+operation, represents a branch from a remote repository which shares
+a common history with the specified
+.Ar branch
+but has at some point diverged due to commits added to the remote repository.
+.Pp
 Rebased commits are accumulated on a temporary branch which the work tree
 will remain switched to throughout the entire rebase operation.
 Commits on this branch represent the same changes with the same log