git/Documentation/git-replace.txt
Elijah Newren 9df53c5de6 Recommend git-filter-repo instead of git-filter-branch
filter-branch suffers from a deluge of disguised dangers that disfigure
history rewrites (i.e. deviate from the deliberate changes).  Many of
these problems are unobtrusive and can easily go undiscovered until the
new repository is in use.  This can result in problems ranging from an
even messier history than what led folks to filter-branch in the first
place, to data loss or corruption.  These issues cannot be backward
compatibly fixed, so add a warning to both filter-branch and its manpage
recommending that another tool (such as filter-repo) be used instead.

Also, update other manpages that referenced filter-branch.  Several of
these needed updates even if we could continue recommending
filter-branch, either due to implying that something was unique to
filter-branch when it applied more generally to all history rewriting
tools (e.g. BFG, reposurgeon, fast-import, filter-repo), or because
something about filter-branch was used as an example despite other more
commonly known examples now existing.  Reword these sections to fix
these issues and to avoid recommending filter-branch.

Finally, remove the section explaining BFG Repo Cleaner as an
alternative to filter-branch.  I feel somewhat bad about this,
especially since I feel like I learned so much from BFG that I put to
good use in filter-repo (which is much more than I can say for
filter-branch), but keeping that section presented a few problems:
  * In order to recommend that people quit using filter-branch, we need
    to provide them a recomendation for something else to use that
    can handle all the same types of rewrites.  To my knowledge,
    filter-repo is the only such tool.  So it needs to be mentioned.
  * I don't want to give conflicting recommendations to users
  * If we recommend two tools, we shouldn't expect users to learn both
    and pick which one to use; we should explain which problems one
    can solve that the other can't or when one is much faster than
    the other.
  * BFG and filter-repo have similar performance
  * All filtering types that BFG can do, filter-repo can also do.  In
    fact, filter-repo comes with a reimplementation of BFG named
    bfg-ish which provides the same user-interface as BFG but with
    several bugfixes and new features that are hard to implement in
    BFG due to its technical underpinnings.
While I could still mention both tools, it seems like I would need to
provide some kind of comparison and I would ultimately just say that
filter-repo can do everything BFG can, so ultimately it seems that it
is just better to remove that section altogether.

Signed-off-by: Elijah Newren <newren@gmail.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
2019-09-05 13:01:48 -07:00

162 lines
5.1 KiB
Plaintext

git-replace(1)
==============
NAME
----
git-replace - Create, list, delete refs to replace objects
SYNOPSIS
--------
[verse]
'git replace' [-f] <object> <replacement>
'git replace' [-f] --edit <object>
'git replace' [-f] --graft <commit> [<parent>...]
'git replace' [-f] --convert-graft-file
'git replace' -d <object>...
'git replace' [--format=<format>] [-l [<pattern>]]
DESCRIPTION
-----------
Adds a 'replace' reference in `refs/replace/` namespace.
The name of the 'replace' reference is the SHA-1 of the object that is
replaced. The content of the 'replace' reference is the SHA-1 of the
replacement object.
The replaced object and the replacement object must be of the same type.
This restriction can be bypassed using `-f`.
Unless `-f` is given, the 'replace' reference must not yet exist.
There is no other restriction on the replaced and replacement objects.
Merge commits can be replaced by non-merge commits and vice versa.
Replacement references will be used by default by all Git commands
except those doing reachability traversal (prune, pack transfer and
fsck).
It is possible to disable use of replacement references for any
command using the `--no-replace-objects` option just after 'git'.
For example if commit 'foo' has been replaced by commit 'bar':
------------------------------------------------
$ git --no-replace-objects cat-file commit foo
------------------------------------------------
shows information about commit 'foo', while:
------------------------------------------------
$ git cat-file commit foo
------------------------------------------------
shows information about commit 'bar'.
The `GIT_NO_REPLACE_OBJECTS` environment variable can be set to
achieve the same effect as the `--no-replace-objects` option.
OPTIONS
-------
-f::
--force::
If an existing replace ref for the same object exists, it will
be overwritten (instead of failing).
-d::
--delete::
Delete existing replace refs for the given objects.
--edit <object>::
Edit an object's content interactively. The existing content
for <object> is pretty-printed into a temporary file, an
editor is launched on the file, and the result is parsed to
create a new object of the same type as <object>. A
replacement ref is then created to replace <object> with the
newly created object. See linkgit:git-var[1] for details about
how the editor will be chosen.
--raw::
When editing, provide the raw object contents rather than
pretty-printed ones. Currently this only affects trees, which
will be shown in their binary form. This is harder to work with,
but can help when repairing a tree that is so corrupted it
cannot be pretty-printed. Note that you may need to configure
your editor to cleanly read and write binary data.
--graft <commit> [<parent>...]::
Create a graft commit. A new commit is created with the same
content as <commit> except that its parents will be
[<parent>...] instead of <commit>'s parents. A replacement ref
is then created to replace <commit> with the newly created
commit. Use `--convert-graft-file` to convert a
`$GIT_DIR/info/grafts` file and use replace refs instead.
--convert-graft-file::
Creates graft commits for all entries in `$GIT_DIR/info/grafts`
and deletes that file upon success. The purpose is to help users
with transitioning off of the now-deprecated graft file.
-l <pattern>::
--list <pattern>::
List replace refs for objects that match the given pattern (or
all if no pattern is given).
Typing "git replace" without arguments, also lists all replace
refs.
--format=<format>::
When listing, use the specified <format>, which can be one of
'short', 'medium' and 'long'. When omitted, the format
defaults to 'short'.
FORMATS
-------
The following format are available:
* 'short':
<replaced sha1>
* 'medium':
<replaced sha1> -> <replacement sha1>
* 'long':
<replaced sha1> (<replaced type>) -> <replacement sha1> (<replacement type>)
CREATING REPLACEMENT OBJECTS
----------------------------
linkgit:git-hash-object[1], linkgit:git-rebase[1], and
https://github.com/newren/git-filter-repo[git-filter-repo], among other git commands, can be used to
create replacement objects from existing objects. The `--edit` option
can also be used with 'git replace' to create a replacement object by
editing an existing object.
If you want to replace many blobs, trees or commits that are part of a
string of commits, you may just want to create a replacement string of
commits and then only replace the commit at the tip of the target
string of commits with the commit at the tip of the replacement string
of commits.
BUGS
----
Comparing blobs or trees that have been replaced with those that
replace them will not work properly. And using `git reset --hard` to
go back to a replaced commit will move the branch to the replacement
commit instead of the replaced commit.
There may be other problems when using 'git rev-list' related to
pending objects.
SEE ALSO
--------
linkgit:git-hash-object[1]
linkgit:git-rebase[1]
linkgit:git-tag[1]
linkgit:git-branch[1]
linkgit:git-commit[1]
linkgit:git-var[1]
linkgit:git[1]
https://github.com/newren/git-filter-repo[git-filter-repo]
GIT
---
Part of the linkgit:git[1] suite