mirror of
https://github.com/newren/git-filter-repo.git
synced 2024-07-03 17:05:39 +02:00
Documentation: add more detailed explanation of safety checks and --force
I occasionally get people doing special things, or see people recommending to others to just use --force. Add some explanations behind the safety checks so that those doing special things know when it's okay, and to explain why it's a really bad idea to casually or haphazardly recommend others use --force. Signed-off-by: Elijah Newren <newren@gmail.com>
This commit is contained in:
parent
3dfaf3874e
commit
1e2d0e91cb
|
@ -283,10 +283,10 @@ Miscellaneous options
|
|||
|
||||
--force::
|
||||
-f::
|
||||
Rewrite history even if the current repo does not look like a fresh
|
||||
clone. Note that when cloning repos on a local filesystem, it is
|
||||
better to pass `--no-local` to git clone than passing `--force` to
|
||||
git-filter-repo.
|
||||
Rewrite history even if the current repo does not look like a
|
||||
fresh clone. See <<FRESHCLONE>>. Note that when cloning
|
||||
repos on a local filesystem, it is better to pass `--no-local`
|
||||
to git clone than passing `--force` to git-filter-repo.
|
||||
|
||||
--partial::
|
||||
Do a partial history rewrite, resulting in the mixture of old and
|
||||
|
@ -328,6 +328,50 @@ Miscellaneous options
|
|||
--quiet::
|
||||
Pass --quiet to other git commands called.
|
||||
|
||||
[[FRESHCLONE]]
|
||||
FRESH CLONE SAFETY CHECK AND --FORCE
|
||||
------------------------------------
|
||||
|
||||
Since filter-repo does irreversible rewriting of history, it is
|
||||
important to avoid making changes to a repo for which the user doesn't
|
||||
have a good backup. The primary defense mechanism is to simply
|
||||
educate users and rely on them to be good stewards of their data; thus
|
||||
there are several warnings in the documentation about how filter repo
|
||||
rewrites history.
|
||||
|
||||
However, as a service to users, we would like to provide an additional
|
||||
safety check beyond the documentation. There isn't a good way to
|
||||
check if the user has a good backup, but we can ask a related question
|
||||
that is an imperfect but quite reasonable proxy: "Is this repository a
|
||||
fresh clone?" Unfortunately, that is also a question we can't get a
|
||||
perfect answer to; git provides no way to answer that question.
|
||||
However, there are approximately a dozen things that I found that seem
|
||||
to always be true of brand new clones, and I check for all of those.
|
||||
|
||||
These checks can have both false positives and false negatives.
|
||||
Someone might have a perfectly good backup of their repo without it
|
||||
actually being a fresh clone -- but there's no way for filter-repo to
|
||||
know that. Conversely, someone could look at all things that
|
||||
filter-repo checks for in its safety checks and then just tweak their
|
||||
non-backed-up repository to satisfy those conditions (though it would
|
||||
take a fair amount of effort, and it's astronomically unlikely that a
|
||||
repo that isn't a fresh clone happens to match all the criteria). In
|
||||
practice, the safety checks filter-repo uses seem to be really good at
|
||||
avoiding people accidentally running filter-repo on a repository that
|
||||
they shouldn't be running it on. It even caught me once when I did
|
||||
mean to run filter-repo but was in a different directory than I
|
||||
thought I was.
|
||||
|
||||
In short, it's perfectly fine to use "--force" to override the safety
|
||||
checks as long as you're okay with filter-repo irreversibly rewriting
|
||||
the contents of the current repository. It is a really bad idea to
|
||||
get in the habit of always specifying --force; if you do, one day you
|
||||
will run one of your commands in the wrong directory like I did, and
|
||||
you won't have the safety check anymore to bail you out. Also, it is
|
||||
definitely NOT okay to recommend --force on forums, Q&A sites, or in
|
||||
emails to other users without first carefully explaining that --force
|
||||
means putting your repositories' data at risk.
|
||||
|
||||
[[VERSATILITY]]
|
||||
VERSATILITY
|
||||
-----------
|
||||
|
|
|
@ -277,9 +277,10 @@ one of the last four traits as well:
|
|||
using that. Almost everyone I've ever seen do a repository
|
||||
filtering operation has done so with a fresh clone, because
|
||||
wiping out the clone in case of error is a vastly easier recovery
|
||||
mechanism. Strongly encourage that workflow by detecting and
|
||||
bailing if we're not in a fresh clone, unless the user overrides
|
||||
with --force.
|
||||
mechanism. Strongly encourage that workflow by [detecting and
|
||||
bailing if we're not in a fresh
|
||||
clone](https://htmlpreview.github.io/?https://github.com/newren/git-filter-repo/blob/docs/html/git-filter-repo.html#FRESHCLONE),
|
||||
unless the user overrides with --force.
|
||||
|
||||
1. [Auto shrink] Automatically remove old cruft and repack the
|
||||
repository for the user after filtering (unless overridden); this
|
||||
|
|
Loading…
Reference in New Issue
Block a user