DESIGN

   1 Patch removal:
   2
   3  - removed patch must be removed from the deps of its
   4    ex-children, and replaced with the deps of the removed
   5    patch
   6
   7  - removed patch wants not to be in list of patches "tb-list"
   8    et al any more
   9       branches in refs/topbloke-tips ?  yes
  10       deleted patches do something to the base ?  no
  11
  12  deleting empty patch: dependencies fine
  13  deleting nonempty patch: if any dependencies found, their
  14     updates break
  15
  16  purpose of deleting?
  17    - remove from views of active patches
  18    - prevent new commits
  19    - remove from dependencies of active patches
  20        only makes sense if no active patches depend on it.
  21
  22  undeleting
  23    - just unmark the patch as deleted
  24
  25
  26 Foreign branches:
  27  When merging from a foreign dependency, check that it
  28  does not have .topbloke metadata
  29
  30 Patch naming:
  31  needs to be globally unique
  32  so put email address in it
  33 tg operations search for applicable patches
  34 safe charset for patch names
  35   . - / 0-9 a-z
  36 not permitted (git-check-ref-format(1))
  37  spc ~ ^ : ? * [ \
  38  @{ .lock.
  39  (apropos of shell)
  40
  41
  42 When pulling, which remotes get to update which patches ?
  43 Complicated question!
  44
  45 For now, have "blessed" remotes, which we always pull and update from.
  46 All these count as sources above.
  47
  48 Update operation restrictions available, which restrict use of various
  49 sources above ?  What about implications for correctness of merge
  50 algorithm ?
  51
  52
  53 Concept of a "stack" ?
  54 Unnecessary - instead, deal with leaf patches
  55 Operations like "go up the stack", goes towards leaf.  Hopefully unique.
  56 "Down" the stack, uses a "conventional" linearisation
  57 Stack reordering op ?  auto adjust deps
  58
  59
  60 When merging, we need to DTRT with our metadata.
  61 Do this by running write-tree/read-tree etc. ourselves ?
  62 For a source we're merging from, we make a version where the
  63 metadata we shouldn't be merging is removed ?
  64 Or something.
  65 Have discovered that specifying a custom merge driver for a file does
  66 not have any effect if the three-way-merge looks trivial based
  67 on looking at the file contents - at least, if you use git-merge.
  68
  69 Only thing which knows how to do all the gitattributes stuff and
  70 conflict markers and what have you is git-merge.  (git-merge-tree does
  71 too but the output format is unsuitable.)  "git-merge-index
  72 ... git-merge-one-file" does not honour the merge drivers and is,
  73 contrary to what the git docs seem to suggest but don't actually
  74 state, not actualy used by git-merge.
  75
  76 OK so here is a plan:
  77   Use git-merge --no-commit
  78   Perhaps on a HEAD, and/or against a tree, which have been massaged
  79    to make the metadata suitable as input.
  80   Filtering out the "merge was successful but we aren't committing"
  81   message.  Use a single pipe for stdout/stderr to get interleaving
  82   right; the message from git-merge is not i18n'd.
  83   Afterwards we:
  84   Check for merge success in the index and compare to exit status
  85   from git-merge (which is 1 if the merge failed).
  86   Adjust the metadata.
  87   Print appropriate big fat warnings if we have merge conflicts in our
  88   metadata.
  89   Commit, adjusting the parents of the new commit to the original
  90   parents if we made the merge with special massaged parents.
  91   We may still need to have custom merge drivers for metadata.
  92
  93
  94 Strategies for each metadata file merge:
  95
  96         in base/tip     same patch & branch     dep -> base     base -> tip
  97
  98  msg             T      textual merge           rm from src     not in src
  99  patch          BT      must be same            rm from src     must be same
 100  base            T      compute specially       rm from src     not in src
 101  deps           B       list merge              rm from src     rm from src
 102  deleted         T      std existence merge     rm from src     not in src
 103  [^+]*-         ??      textual merge           rm from src     rm from src
 104  +included      BT      list merge        rm from non-tb src    list merge
 105  +ends          BT      compute specially       compute specially
 106  +*-            ??      textual merge     rm from non-tb src    textual merge
 107  *[^-]          ??      die, aborting all ops, if found in any tb src or branch