git-filter-repo.txt: discourage use of random clone flags

Flags like --local, --shared, --reference (and --dissociate), and
--origin would all mess up the fresh clone checker.  Attempting to
defend against all of them would not only be costly, but make it harder
to draw the line about guesses as to whether a repository is a fresh
clone or not.  --origin also has problems in that filter-repo has
special handling for the 'origin' remote that I don't want to apply to
other random remotes.

Flags like --depth, --single-branch, and --no-tags could prevent enough
data from being downloaded to do a full rewrite and result in a
partially rewritten or possibly even corrupt history (no idea how
shallow clones interact; probably badly).  --filter would also make the
repo start without enough info though it'd at least be downloaded on
demand; it'd still be a really slow way to do it, though, so it's a bad
idea.

filter-repo doesn't really provide an easy mechanism to rewrite a repo
and its submodule simultaneously, so recursing submodules seems useless
and unhelpful.  --shallow-submodules would be bad for at least the same
reasons --depth is for the parent module, assuming we handled
submodules.  --remote-submodules just provides a way to make the repo
dirty to start, which is counter-productive.  --jobs could be useful, if
recursing submodules was.

--no-checkout might be safe to use and --sparse might also be okay for
as long as it only affects the working tree, but in both cases why not
go --bare or --mirror if you're doing that?  Likewise, --no-hardlinks is
useless given that we're already saying people need to use --no-local.

-b would be okay to use, but why wouldn't you just change the default
branch on the server rather than just within this one clone used for
rewriting the history?  Whether you push back to the original repository
or to a new repo, you'd have to take a separate step to change it in
that remote repo.  And if you really will use this new local repository
as the official source, then you can switch branches at the end of the
rewrite just as easily.

--separate-git-dir and --template might be okay to use, I haven't
tested.  If either doesn't work now, or breaks at any point in the
future, I feel much better being able to say, "I told you to only use
these three flags to git clone."

-u only affects the ability to receive the clone; it's fine to use.
Also, -q only affects the console output during the clone operation, so
you could use it.

There will probably be more flags added to git-clone over time.  Testing
against all of them is insanity.  Recommend people only use --no-local,
--bare, and --mirror, with the first only needed when cloning from a
local filesystem, and the other two never needed but allowed for those
that prefer.

Signed-off-by: Elijah Newren <[email protected]>

Documentation/git-filter-repo.txt

@@ -431,8 +431,12 @@ Steps to use git-filter-repo as part of the bigger picture of doing a
 history rewrite are roughly as follows:
 
 1. Create a clone of your repository (if you created special refs outside
-   of refs/heads/ or refs/tags/, make sure to fetch those too).  Note
-   that `--bare` and `--mirror` clones are supported too, if you prefer.
+   of refs/heads/ or refs/tags/, make sure to fetch those too).  You may
+   pass `--bare` or `--mirror` to `git clone`, if you prefer.  You should
+   pass `--no-local` if the repository you are cloning from is on the local
+   filesystem.  Avoid other flags; some might confuse the fresh clone
+   check, and others could cause parts of the data to be missing that are
+   needed for the rewrite.
 
 2. (Optional) Run `git filter-repo --analyze`.  This will create a
    directory of reports mentioning renames that have occurred in your