git-filter-repo.txt: be more forceful on the wording of --force

Online blogs/articles/Q&A as well as direct feedback suggests that
people use the --force flag rather cavalierly.  Add words like
"irreversible" and "immediate pruning" to discourage such blithe
application of this flag.  I hope this encourages folks to either learn
the ramifications of irreversible full-repository entire history
rewrites first, or to follow the recommendation of only operating on a
fresh clone.

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

Author: newren

Documentation/git-filter-repo.txt

@@ -296,10 +296,12 @@ Miscellaneous options
 
 --force::
 -f::
-	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.
+	Ignore fresh clone checks and rewrite history (an irreversible
+	operation, especially since it by default ends with an
+	immediate pruning of reflogs and old objects).  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

git-filter-repo

@@ -1956,8 +1956,10 @@ EXAMPLES
     misc.add_argument('--version', action='store_true',
         help=_("Display filter-repo's version and exit."))
     misc.add_argument('--force', '-f', action='store_true',
-        help=_("Rewrite history even if the current repo does not look "
-               "like a fresh clone."))
+        help=_("Rewrite repository history even if the current repo does not "
+               "look like a fresh clone.  History rewriting is irreversible "
+               "(and includes immediate pruning of reflogs and old objects), "
+               "so be cautious about using this flag."))
     misc.add_argument('--partial', action='store_true',
         help=_("Do a partial history rewrite, resulting in the mixture of "
                "old and new history.  This implies a default of "