@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.) hq.recaptime.dev/wiki/Phorge
phorge phabricator
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Document the use of repository commit hints

Summary: Ref T11522. This explains how to actually use `bin/repository hint`.

Test Plan: Read the document. Used `bin/repository hint` as directed.

Reviewers: chad

Reviewed By: chad

Maniphest Tasks: T11522

Differential Revision: https://secure.phabricator.com/D16441

+134
+134
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.