[PATCH 4/8] t5800: document some non-functional parts of remote helpers

These are all things one might expect to work in a helper that is capable of handling multiple branches (which our testgit helper in theory should be able to do, as it is backed by git). All of these bugs are specific to the import/export codepaths, so they don't affect helpers like git-remote-curl that use fetch/push commands.

The first and fourth tests are about fetching and pushing new refs, and demonstrate bugs in the git_remote_helpers library (so they would be most likely to impact helpers for other VCSs which import/export git).

The second test is about importing multiple refs; it demonstrates a bug in git-remote-testgit, which is mostly for exercising the test code. Therefore it probably doesn't affect anyone in practice.

The third test demonstrates a bug in git's side of the helper code when the upstream has added new refs without us. This could impact git users who use remote helpers to access foreign VCSs.

All of those bugs have fixes later in this series.

The fifth test is the most complex, and does not have a fix in this series. It tests pushing a ref via the export mechanism to a new name on the remote side (i.e., "git push $remote old:new").

The problem is that we push all of the work of generating the export stream onto fast-export, but we have no way of communicating to fast-export that this name mapping is happening. So we tell fast-export to generate a stream with the commits for "old", but we can't tell it to label them all as "new".

There are two possible solutions:

  1. Indicate the mapping to fast-export, so that it can
     generate the "mapped" names. Unfortunately, this is
     somewhat difficult due to the way fast-import is
     implemented. It feeds its revision parameters to the
     regular rev-walking machinery, asking the revision code
     to mark the "source" of each commit. So if fast-export
     sees that we want commits from "refs/heads/old", but
     also that we want to call commits from old as
     "refs/heads/new", it can't distinguish between the
     case of "I want _only_ new, using the commits of old"
     and "I want _both_ old and new, which happen to point
     to the same commits".

     And it's important to distinguish those cases, because
     in one, the remote will update master, and in the
     other, it will not.

     This isn't an insurmountable obstacle, but it's going
     to mean either fast-export has to take on more of the
     revision argument parsing and revwalking
     responsibility, or the revision walker's show_source
     code will have to learn about mapping names.

  2. Indicate the mapping to the remote helper, who can then
     apply the mapping to the results of the export. Right
     now the export remote helper command has no arguments;
     it simply says "hey, I'm going to dump a fast-export
     stream on you". And the remote-helper looks through the
     results of the stream to decide which refs are being
     pushed. This could be extended instead to something
     like:

       export refs/heads/foo
       export refs/heads/old:refs/heads/new
       <blank line>

     which would allow the remote helper to map names as
     appropriate. This a reasonably elegant solution; the
     downside is that it breaks compatibility with existing
     remote helpers.

Signed-off-by: Jeff King <peff@peff.net>
---
 t/t5800-remote-helpers.sh |   47 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 47 insertions(+), 0 deletions(-)