src/docs/user/field/repository_hints.diviner

   1 @title Repository Hints and Rewriting Commits
   2 @group fieldmanual
   3
   4 Dealing with rewrites of published repositories and other unusual problems.
   5
   6 Overview
   7 ========
   8
   9 Some repositories have unusual commits. You can provide "hints" to Phabricator
  10 about these commits to improve behavior.
  11
  12 Supported hints are:
  13
  14   - **Rewritten Commits**: If you have rewritten the history of a published
  15     repository, you can provide hints about the mapping from old commits to
  16     new commits so it can redirect users who visit old pages to the proper
  17     new pages.
  18   - **Unreadable Commits**: If some commits are not readable (which is rare,
  19     but can happen in some cases if they are generated with an external tool)
  20     you can provide hints so that Phabricator doesn't try to read them.
  21
  22 The remainder of this document explains how to create and remove hints, and how
  23 to specify each type of hint.
  24
  25 Creating Hints
  26 ==============
  27
  28 To create hints, pipe a JSON list of hints to `bin/repository hint`:
  29
  30 ```
  31 phabricator/ $ cat hints.json | ./bin/repository hint
  32 ```
  33
  34 The hints should be a list of objects like this:
  35
  36 ```lang=json
  37 [
  38   ...
  39   {
  40     "repository": "XYZ",
  41     "hint": "...",
  42     "old": "abcdef1234abcdef1234abcdef1234abcdef1234",
  43     "new": "..."
  44   }
  45   ...
  46 ]
  47 ```
  48
  49 Each hint may have these keys:
  50
  51   - `repository`: A repository identifier (ID, PHID, callsign or short name).
  52   - `hint`: The hint type, see below.
  53   - `old`: The full identifier or commit hash of the commit you want to
  54     provide a hint for.
  55   - `new`: For hints which specify a new commit, the full identifier or commit
  56     hash of the new commit.
  57
  58 See below for exactly how to specify each type of hint.
  59
  60
  61 Removing Hints
  62 ==============
  63
  64 To remove a hint, create a hint of type `"none"`. This will remove any existing
  65 hint.
  66
  67 For example, use a hint specification like this:
  68
  69 ```lang=json
  70 [
  71   {
  72     "repository": "XYZ",
  73     "hint": "none",
  74     "old": "abcdef1234abcdef1234abcdef1234abcdef1234"
  75   }
  76 ]
  77 ```
  78
  79 Phabricator won't treat commits without any hint specially.
  80
  81
  82 Hint: Rewritten Commits
  83 =======================
  84
  85 The `"rewritten"` hint allows you to redirect old commits to new commits after
  86 a rewrite of published history. You should normally avoid rewriting published
  87 commits, but sometimes this is necessary: for example, if a repository has
  88 become unwieldy because it contains large binaries, you may strip them from
  89 history.
  90
  91 To provide this kind of hint, pass the `"old"` commit hash (from before the
  92 rewrite) and the `"new"` commit hash (from after the rewrite).
  93
  94 For example, a hint might look like this:
  95
  96 ```lang=json
  97 [
  98   {
  99     "repository": "XYZ",
 100     "hint": "rewritten",
 101     "old": "abcdef1234abcdef1234abcdef1234abcdef1234",
 102     "new": "098765ffaabbccdd4680098765ffaabbccdd4680"
 103   }
 104 ]
 105 ```
 106
 107 Phabricator will show users that the commit was rewritten in the web UI.
 108
 109
 110 Hint: Unreadable Commits
 111 ========================
 112
 113 The `"unreadable"` hint allows you to tell Phabricator that it should not
 114 bother trying to read the changes associated with a particular commit. In
 115 some rare cases, repositories can contain commits which aren't readable
 116 (for example, if they were created by external tools during an import or
 117 merge process).
 118
 119 To provide this kind of hint, pass the `"old"` commit which is affected.
 120
 121 For example, a hint might look like this:
 122
 123 ```lang=json
 124 [
 125   {
 126     "repository": "XYZ",
 127     "hint": "unreadable",
 128     "old": "abcdef1234abcdef1234abcdef1234abcdef1234"
 129   }
 130 ]
 131 ```
 132
 133 Phabricator won't try to read, parse, import, or display the changes associated
 134 with this commit.