technical/shallow: describe why shallow cannot use replace refs
It is tempting to do away with commit_graft altogether (in the long haul), now that grafts are deprecated. However, the shallow feature needs a couple of things that the replace refs cannot fulfill. Let's point that out in the documentation. Signed-off-by: Johannes Schindelin <johannes.schindelin@gmx.de> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Johannes Schindelin committed
Apr 29, 2018 at 00:45 UTC
f42fa470b0d87fcb36475f78f2366bba6864895a
1 file changed
+7
Documentation/technical/shallow.txt
+7
@@ -17,6 +17,13 @@ Each line contains exactly one SHA-1. When read, a commit_graft
17
will be constructed, which has nr_parent < 0 to make it easier
18
to discern from user provided grafts.
19
20
+Note that the shallow feature could not be changed easily to
21
+use replace refs: a commit containing a `mergetag` is not allowed
22
+to be replaced, not even by a root commit. Such a commit can be
23
+made shallow, though. Also, having a `shallow` file explicitly
24
+listing all the commits made shallow makes it a *lot* easier to
25
+do shallow-specific things such as to deepen the history.
26
+
27
Since fsck-objects relies on the library to read the objects,
28
it honours shallow commits automatically.
29