From a238e3b7e60730969877192c3dbcfdcd053f1619 Mon Sep 17 00:00:00 2001 From: Elijah Newren Date: Sat, 13 Jun 2020 21:06:08 -0700 Subject: [PATCH] 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 --- Documentation/git-filter-repo.txt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/Documentation/git-filter-repo.txt b/Documentation/git-filter-repo.txt index 5f27b50..ff21ff8 100644 --- a/Documentation/git-filter-repo.txt +++ b/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