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