On Sat, Nov 10, 2018 at 10:36 PM Jeff King <peff@xxxxxxxx> wrote: > > On Sat, Nov 10, 2018 at 10:23:04PM -0800, Elijah Newren wrote: > > > Signed-off-by: Elijah Newren <newren@xxxxxxxxx> > > --- > > Documentation/git-fast-export.txt | 3 ++- > > 1 file changed, 2 insertions(+), 1 deletion(-) > > > > diff --git a/Documentation/git-fast-export.txt b/Documentation/git-fast-export.txt > > index ce954be532..677510b7f7 100644 > > --- a/Documentation/git-fast-export.txt > > +++ b/Documentation/git-fast-export.txt > > @@ -119,7 +119,8 @@ marks the same across runs. > > 'git rev-list', that specifies the specific objects and references > > to export. For example, `master~10..master` causes the > > current master reference to be exported along with all objects > > - added since its 10th ancestor commit. > > + added since its 10th ancestor commit and all files common to > > + master\~9 and master~10. > > Do you need to backslash the second tilde? Maybe `master~9` and > `master~10` instead of escaping? Oops, yeah, that needs to be consistent. > I'm not sure what this is trying to say. I guess that we'd always show > all of the blobs necessary to reconstruct the first non-negative commit > (i.e., `master~9` here)? For someone familiar with fast-export or fast-import, sure, you'd guess that it'd show all the blobs necessary to reconstruct the first non-negative commit. But it's not clear to first time users and readers of the docs that the first non-negative commit becomes a root commit; by comparison, filter-branch suggests using a very similar construction and yet behaves quite differently -- it does not turn the first non-negative commit into a root but retains the original parent(s) of the first non-negative commit without rewriting those earlier commits. The text as previously written, "along with all objects added since its 10th ancestor commit", seems to suggest behavior similar to how filter-branch behaves (particularly the "Acked-by example"), i.e. it implies that files not touched in the last 10 commits are not included. My wording in this patch was an attempt to fix that. Was my attempt perhaps too clumsy, or was it just the case that you had sufficient knowledge of fast-export that the previous text didn't mislead you?
