Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/field/repository_hints.diviner
@title Repository Hints and Rewriting Commits | @title Repository Hints and Rewriting Commits | ||||
@group fieldmanual | @group fieldmanual | ||||
Dealing with rewrites of published repositories and other unusual problems. | Dealing with rewrites of published repositories and other unusual problems. | ||||
Overview | Overview | ||||
======== | ======== | ||||
Some repositories have unusual commits. You can provide "hints" to Phabricator | Some repositories have unusual commits. You can provide "hints" to Phorge | ||||
about these commits to improve behavior. | about these commits to improve behavior. | ||||
Supported hints are: | Supported hints are: | ||||
- **Rewritten Commits**: If you have rewritten the history of a published | - **Rewritten Commits**: If you have rewritten the history of a published | ||||
repository, you can provide hints about the mapping from old commits to | repository, you can provide hints about the mapping from old commits to | ||||
new commits so it can redirect users who visit old pages to the proper | new commits so it can redirect users who visit old pages to the proper | ||||
new pages. | new pages. | ||||
- **Unreadable Commits**: If some commits are not readable (which is rare, | - **Unreadable Commits**: If some commits are not readable (which is rare, | ||||
but can happen in some cases if they are generated with an external tool) | but can happen in some cases if they are generated with an external tool) | ||||
you can provide hints so that Phabricator doesn't try to read them. | you can provide hints so that Phorge doesn't try to read them. | ||||
The remainder of this document explains how to create and remove hints, and how | The remainder of this document explains how to create and remove hints, and how | ||||
to specify each type of hint. | to specify each type of hint. | ||||
Creating Hints | Creating Hints | ||||
============== | ============== | ||||
To create hints, pipe a JSON list of hints to `bin/repository hint`: | To create hints, pipe a JSON list of hints to `bin/repository hint`: | ||||
``` | ``` | ||||
phabricator/ $ cat hints.json | ./bin/repository hint | phorge/ $ cat hints.json | ./bin/repository hint | ||||
``` | ``` | ||||
The hints should be a list of objects like this: | The hints should be a list of objects like this: | ||||
```lang=json | ```lang=json | ||||
[ | [ | ||||
... | ... | ||||
{ | { | ||||
Show All 31 Lines | [ | ||||
{ | { | ||||
"repository": "XYZ", | "repository": "XYZ", | ||||
"hint": "none", | "hint": "none", | ||||
"old": "abcdef1234abcdef1234abcdef1234abcdef1234" | "old": "abcdef1234abcdef1234abcdef1234abcdef1234" | ||||
} | } | ||||
] | ] | ||||
``` | ``` | ||||
Phabricator won't treat commits without any hint specially. | Phorge won't treat commits without any hint specially. | ||||
Hint: Rewritten Commits | Hint: Rewritten Commits | ||||
======================= | ======================= | ||||
The `"rewritten"` hint allows you to redirect old commits to new commits after | The `"rewritten"` hint allows you to redirect old commits to new commits after | ||||
a rewrite of published history. You should normally avoid rewriting published | a rewrite of published history. You should normally avoid rewriting published | ||||
commits, but sometimes this is necessary: for example, if a repository has | commits, but sometimes this is necessary: for example, if a repository has | ||||
Show All 11 Lines | [ | ||||
"repository": "XYZ", | "repository": "XYZ", | ||||
"hint": "rewritten", | "hint": "rewritten", | ||||
"old": "abcdef1234abcdef1234abcdef1234abcdef1234", | "old": "abcdef1234abcdef1234abcdef1234abcdef1234", | ||||
"new": "098765ffaabbccdd4680098765ffaabbccdd4680" | "new": "098765ffaabbccdd4680098765ffaabbccdd4680" | ||||
} | } | ||||
] | ] | ||||
``` | ``` | ||||
Phabricator will show users that the commit was rewritten in the web UI. | Phorge will show users that the commit was rewritten in the web UI. | ||||
Hint: Unreadable Commits | Hint: Unreadable Commits | ||||
======================== | ======================== | ||||
The `"unreadable"` hint allows you to tell Phabricator that it should not | The `"unreadable"` hint allows you to tell Phorge that it should not | ||||
bother trying to read the changes associated with a particular commit. In | bother trying to read the changes associated with a particular commit. In | ||||
some rare cases, repositories can contain commits which aren't readable | some rare cases, repositories can contain commits which aren't readable | ||||
(for example, if they were created by external tools during an import or | (for example, if they were created by external tools during an import or | ||||
merge process). | merge process). | ||||
To provide this kind of hint, pass the `"old"` commit which is affected. | To provide this kind of hint, pass the `"old"` commit which is affected. | ||||
For example, a hint might look like this: | For example, a hint might look like this: | ||||
```lang=json | ```lang=json | ||||
[ | [ | ||||
{ | { | ||||
"repository": "XYZ", | "repository": "XYZ", | ||||
"hint": "unreadable", | "hint": "unreadable", | ||||
"old": "abcdef1234abcdef1234abcdef1234abcdef1234" | "old": "abcdef1234abcdef1234abcdef1234abcdef1234" | ||||
} | } | ||||
] | ] | ||||
``` | ``` | ||||
Phabricator won't try to read, parse, import, or display the changes associated | Phorge won't try to read, parse, import, or display the changes associated | ||||
with this commit. | with this commit. |
Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0