9df53c5de6
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>
162 lines
5.1 KiB
Plaintext
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
|