Re: grafts not appearing in manual pages

Johannes Sixt [off-list ref] writes:

J. Bruce Fields schrieb:
...

quoted

It could go in Documentation/user-manual.txt, but I don't know where.

IMHO grafts should not be made known to a wide audience until
send-pack, pack-objects, and prune are fixed so that you cannot
corrupt your repository when there are grafts.

I mildly have to disagree.

Documenting the current semantics (in short, "grafts are
strictly local matter") and the implications is important.

Here are some of the points you would want to mention:

 - if you graft, prune and fsck will honor that fake ancestry,

 - if you _add_ parent by grafting you will not lose the history
   that is otherwise disconnected, but on the other hand, once
   having pruned that way and you remove that graft, prune will
   discard that discontiguous history away.

 - if you _hide_ parent by grafting, you will be able to lose
   the hidden subbranch away, but you will get complaints from
   fsck if you remove that graft after pruning your history.

 - if you try to fetch/push across repositories with different
   notion of ancestry (because of different grafts), things can
   break in expected ways (and you can keep both halves ;-).
   For example, if the sending side has extra parents to a
   commit compared to the receiving side, and if the receiving
   side claims to have that commit, objects reachable from the
   extra parents might be missing from the reciving end but the
   sender will not be able to notice.

See http://thread.gmane.org/gmane.comp.version-control.git/37744
in particular http://article.gmane.org/gmane.comp.version-control.git/37866
on a sketch how to fix the issues.

IIRC, there discussions were more about what the issues are and
what the potential semantics could be.  First the desired
semantics need to be defined.