path: root/Documentation
diff options
authorJunio C Hamano <>2018-05-23 05:38:17 (GMT)
committerJunio C Hamano <>2018-05-23 05:38:17 (GMT)
commit352cf6cfe138b1dbcf9c105c91ca793b67511d7b (patch)
treec7aa5bc4bc01eafeb06d8c000397da6b881e95a7 /Documentation
parent5002702e487dc501702b29e768b78d5c22114425 (diff)
parenta3694d949fcd39f9a909cf762f698df8ce83215c (diff)
Merge branch 'js/deprecate-grafts'
The functionality of "$GIT_DIR/info/grafts" has been superseded by the "refs/replace/" mechanism for some time now, but the internal code had support for it in many places, which has been cleaned up in order to drop support of the "grafts" mechanism. * js/deprecate-grafts: Remove obsolete script to convert grafts to replace refs technical/shallow: describe why shallow cannot use replace refs technical/shallow: stop referring to grafts filter-branch: stop suggesting to use grafts Deprecate support for .git/info/grafts Add a test for `git replace --convert-graft-file` replace: introduce --convert-graft-file replace: prepare create_graft() for converting graft files wholesale replace: "libify" create_graft() and callees replace: avoid using die() to indicate a bug commit: Let the callback of for_each_mergetag return on error argv_array: offer to split a string by whitespace
Diffstat (limited to 'Documentation')
3 files changed, 20 insertions, 13 deletions
diff --git a/Documentation/git-filter-branch.txt b/Documentation/git-filter-branch.txt
index b634043..1d4d2f8 100644
--- a/Documentation/git-filter-branch.txt
+++ b/Documentation/git-filter-branch.txt
@@ -288,7 +288,7 @@ git filter-branch --parent-filter \
or even simpler:
-echo "$commit-id $graft-id" >> .git/info/grafts
+git replace --graft $commit-id $graft-id
git filter-branch $graft-id..HEAD
diff --git a/Documentation/git-replace.txt b/Documentation/git-replace.txt
index e5c57ae..246dc99 100644
--- a/Documentation/git-replace.txt
+++ b/Documentation/git-replace.txt
@@ -11,6 +11,7 @@ SYNOPSIS
'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>]]
@@ -87,9 +88,13 @@ OPTIONS
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. See contrib/ for an
- example script based on this option that can convert grafts to
- replace refs.
+ commit. Use `--convert-graft-file` to convert a
+ `$GIT_DIR/info/grafts` file and use replace refs instead.
+ 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>::
diff --git a/Documentation/technical/shallow.txt b/Documentation/technical/shallow.txt
index 5183b15..01dedfe 100644
--- a/Documentation/technical/shallow.txt
+++ b/Documentation/technical/shallow.txt
@@ -8,20 +8,22 @@ repo, and therefore grafts are introduced pretending that
these commits have no parents.
-The basic idea is to write the SHA-1s of shallow commits into
-$GIT_DIR/shallow, and handle its contents like the contents
-of $GIT_DIR/info/grafts (with the difference that shallow
-cannot contain parent information).
-This information is stored in a new file instead of grafts, or
-even the config, since the user should not touch that file
-at all (even throughout development of the shallow clone, it
-was never manually edited!).
+$GIT_DIR/shallow lists commit object names and tells Git to
+pretend as if they are root commits (e.g. "git log" traversal
+stops after showing them; "git fsck" does not complain saying
+the commits listed on their "parent" lines do not exist).
Each line contains exactly one SHA-1. When read, a commit_graft
will be constructed, which has nr_parent < 0 to make it easier
to discern from user provided grafts.
+Note that the shallow feature could not be changed easily to
+use replace refs: a commit containing a `mergetag` is not allowed
+to be replaced, not even by a root commit. Such a commit can be
+made shallow, though. Also, having a `shallow` file explicitly
+listing all the commits made shallow makes it a *lot* easier to
+do shallow-specific things such as to deepen the history.
Since fsck-objects relies on the library to read the objects,
it honours shallow commits automatically.