@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 all the hypothetical URI features we plan to support soon
Summary: Ref T10748. Ref T10366. This documents how everything is planned to work shortly.
Test Plan: Read documentation.
Reviewers: chad
Reviewed By: chad
Subscribers: eadler, scode
Maniphest Tasks: T10366, T10748
Differential Revision: https://secure.phabricator.com/D15817
+254
-33
+24
-31
src/applications/repository/storage/PhabricatorRepositoryURI.php
+24
-31
src/applications/repository/storage/PhabricatorRepositoryURI.php
···
105
105
public function getEffectiveDisplayType() {
106
106
$display = $this->getDisplayType();
107
107
108
-
if ($display != self::IO_DEFAULT) {
108
+
if ($display != self::DISPLAY_DEFAULT) {
109
109
return $display;
110
110
}
111
111
···
116
116
switch ($this->getEffectiveIOType()) {
117
117
case self::IO_MIRROR:
118
118
case self::IO_OBSERVE:
119
-
return self::DISPLAY_NEVER;
120
119
case self::IO_NONE:
121
-
if ($this->isBuiltin()) {
122
-
return self::DISPLAY_NEVER;
123
-
} else {
124
-
return self::DISPLAY_ALWAYS;
125
-
}
120
+
return self::DISPLAY_NEVER;
126
121
case self::IO_READ:
127
122
case self::IO_READWRITE:
128
123
// By default, only show the "best" version of the builtin URI, not the
129
124
// other redundant versions.
130
-
if ($this->isBuiltin()) {
131
-
$repository = $this->getRepository();
132
-
$other_uris = $repository->getURIs();
125
+
$repository = $this->getRepository();
126
+
$other_uris = $repository->getURIs();
133
127
134
-
$identifier_value = array(
135
-
self::BUILTIN_IDENTIFIER_CALLSIGN => 3,
136
-
self::BUILTIN_IDENTIFIER_SHORTNAME => 2,
137
-
self::BUILTIN_IDENTIFIER_ID => 1,
138
-
);
128
+
$identifier_value = array(
129
+
self::BUILTIN_IDENTIFIER_CALLSIGN => 3,
130
+
self::BUILTIN_IDENTIFIER_SHORTNAME => 2,
131
+
self::BUILTIN_IDENTIFIER_ID => 1,
132
+
);
139
133
140
-
$have_identifiers = array();
141
-
foreach ($other_uris as $other_uri) {
142
-
if ($other_uri->getIsDisabled()) {
143
-
continue;
144
-
}
134
+
$have_identifiers = array();
135
+
foreach ($other_uris as $other_uri) {
136
+
if ($other_uri->getIsDisabled()) {
137
+
continue;
138
+
}
145
139
146
-
$identifier = $other_uri->getBuiltinIdentifier();
147
-
if (!$identifier) {
148
-
continue;
149
-
}
140
+
$identifier = $other_uri->getBuiltinIdentifier();
141
+
if (!$identifier) {
142
+
continue;
143
+
}
150
144
151
-
$have_identifiers[$identifier] = $identifier_value[$identifier];
152
-
}
145
+
$have_identifiers[$identifier] = $identifier_value[$identifier];
146
+
}
153
147
154
-
$best_identifier = max($have_identifiers);
155
-
$this_identifier = $identifier_value[$this->getBuiltinIdentifier()];
148
+
$best_identifier = max($have_identifiers);
149
+
$this_identifier = $identifier_value[$this->getBuiltinIdentifier()];
156
150
157
-
if ($this_identifier < $best_identifier) {
158
-
return self::DISPLAY_NEVER;
159
-
}
151
+
if ($this_identifier < $best_identifier) {
152
+
return self::DISPLAY_NEVER;
160
153
}
161
154
162
155
return self::DISPLAY_ALWAYS;
+230
-2
src/docs/user/userguide/diffusion_uris.diviner
+230
-2
src/docs/user/userguide/diffusion_uris.diviner
···
9
9
WARNING: This document describes a feature which is still under development,
10
10
and is not necessarily accurate or complete.
11
11
12
-
Phabricator can host, observe, mirror, and proxy repositories. For example,
13
-
here are some supported use cases:
12
+
Phabricator can create, host, observe, mirror, proxy, and import repositories.
13
+
For example, you can:
14
14
15
15
**Host Repositories**: Phabricator can host repositories locally. Phabricator
16
16
maintains the writable master version of the repository, and you can push and
···
45
45
and so on. By configuring all the URIs that a repository should interact with
46
46
and expose to users, you configure the read, write, and mirroring behavior
47
47
of the repository.
48
+
49
+
The remainder of this document walks through this configuration in greater
50
+
detail.
51
+
52
+
53
+
Host a Repository
54
+
=================
55
+
56
+
You can create new repositories that Phabricator will host, like you would
57
+
create repositories on services like GitHub or Bitbucket. Phabricator will
58
+
serve a read-write copy of the repository and you can clone it from Phabricator
59
+
and push changes to Phabricator.
60
+
61
+
If you haven't already, you may need to configure Phabricator for hosting
62
+
before you can create your first hosted repository. For a detailed guide,
63
+
see @{article:Diffusion User Guide: Repository Hosting}.
64
+
65
+
This is the default mode for new repositories. To host a repository:
66
+
67
+
- Create a new repository.
68
+
- Activate it.
69
+
70
+
Phabricator will create an empty repository and allow you to fetch from it and
71
+
push to it.
72
+
73
+
74
+
Observe a Repository
75
+
====================
76
+
77
+
If you have an existing repository hosted on another service (like GitHub,
78
+
Bitbucket, or a private server) that you want to work with in Phabricator,
79
+
you can configure Phabricator to observe it.
80
+
81
+
When observing a repository, Phabricator will keep track of changes in the
82
+
remote repository and allow you to browse and interact with the repository from
83
+
the web UI in Diffusion and other applications, but you can continue hosting it
84
+
elsewhere.
85
+
86
+
To observe a repository:
87
+
88
+
- Create a new repository, but don't activate it yet.
89
+
- Add the remote URI you want to observe as a repository URI.
90
+
- Set the **I/O Type** for the URI to **Observe**.
91
+
- If necessary, configure a credential.
92
+
- Activate the repository.
93
+
94
+
Phabricator will perform an initial import of the repository, creating a local
95
+
read-only copy. Once this process completes, it will continue keeping track of
96
+
changes in the remote, fetching them, and reflecting them in the UI.
97
+
98
+
99
+
Mirror a Repository
100
+
===================
101
+
102
+
NOTE: Mirroring is not supported in Subversion.
103
+
104
+
You can create a read-only mirror of an existing repository. Phabricator will
105
+
push all changes made to the repository to the mirror.
106
+
107
+
For example, if you have a repository hosted in Phabricator that you want to
108
+
mirror to GitHub, you can configure Phabricator to automatically maintain the
109
+
mirror. This is how the upstream repositories are set up.
110
+
111
+
You can mirror any repository, even if Phabricator is only observing it and not
112
+
hosting it directly.
113
+
114
+
To begin mirroring a repository:
115
+
116
+
- Create a hosted or observed repository by following the relevant
117
+
instructions above.
118
+
- Add the remote URI you want to mirror to as a repository URI.
119
+
- Set the **I/O Type** for the URI to **Mirror**.
120
+
- If necessary, configure a credential.
121
+
122
+
To stop mirroring:
123
+
124
+
- Disable the mirror URI; or
125
+
- Change the **I/O Type** for the URI to **None**.
126
+
127
+
128
+
Import a Repository
129
+
===================
130
+
131
+
If you have an existing repository that you want to move so it is hosted on
132
+
Phabricator, there are three ways to do it:
133
+
134
+
**Push Everything**: //(Git, Mercurial)// Create a new empty hosted repository
135
+
according to the instructions above. Once the empty repository initializes,
136
+
push your entire existing repository to it.
137
+
138
+
**Observe First**: //(Git, Mercurial)// Observe the existing repository first,
139
+
according to the instructions above. Once Phabricator's copy of the repository
140
+
is fully synchronized, change the **I/O Type** for the **Observe** URI to
141
+
**None** to stop fetching changes from the remote.
142
+
143
+
By default, this will automatically make Phabricator's copy of the repository
144
+
writable, and you can begin pushing to it. If you've adjusted URI
145
+
configuration away from the defaults, you may need to set at least one URI
146
+
to **Read/Write** mode so you can push to it.
147
+
148
+
**Copy on Disk**: //(Git, Mercurial, Subversion)// Create a new empty hosted
149
+
repository according to the instructions above, but do not activate it yet.
150
+
151
+
Using the **Storage** tab, find the location of the repository's working copy
152
+
on disk, and place a working copy of the repository you wish to import there.
153
+
154
+
For Git and Mercurial, use a bare working copy for best results.
155
+
156
+
This is the only way to import a Subversion repository because only the master
157
+
copy of the repository has history.
158
+
159
+
Once you've put a working copy in the right place on disk, activate the
160
+
repository.
161
+
162
+
163
+
Customizing Displayed Clone URIs
164
+
================================
165
+
166
+
If you have an unusual configuration and want the UI to offers users specific
167
+
clone URIs other than the URIs that Phabricator serves or interacts with, you
168
+
can add those URIs with the **I/O Type** set to **None** and then set their
169
+
**Display Type** to **Always**.
170
+
171
+
Likewise, you can set the **Display Type** of any URIs you do //not// want
172
+
to be visible to **Never**.
173
+
174
+
This allows you to precisely configure which clone URIs are shown to users for
175
+
a repository.
176
+
177
+
178
+
Reference: I/O Types
179
+
====================
180
+
181
+
This section details the available **I/O Type** options for URIs.
182
+
183
+
Each repository has some **builtin** URIs. These are URIs hosted by Phabricator
184
+
itself. The modes available for each URI depend primarily on whether it is a
185
+
builtin URI or not.
186
+
187
+
**Default**: This setting has Phabricator guess the correct option for the
188
+
URI.
189
+
190
+
For **builtin** URIs, the default behavior is //Read/Write// if the repository
191
+
is hosted, and //Read-Only// if the repository is observed.
192
+
193
+
For custom URIs, the default type is //None// because we can not automatically
194
+
guess if you want to ignore, observe, or mirror a URI and //None// is the
195
+
safest default.
196
+
197
+
**Observe**: Phabricator will observe this repository and regularly fetch any
198
+
changes made to it to a local read-only copy.
199
+
200
+
You can not observe builtin URIs because reading a repository from itself
201
+
does not make sense.
202
+
203
+
You can not add a URI in Observe mode if an existing builtin URI is in
204
+
//Read/Write// mode, because this would mean the repository had two different
205
+
authorities: the observed remote copy and the hosted local copy. Take the
206
+
other URI out of //Read/Write// mode first.
207
+
208
+
**Mirror**: Phabricator will push any changes made to this repository to the
209
+
remote URI, keeping a read-only mirror hosted at that URI up to date.
210
+
211
+
This works for both observed and hosted repositories.
212
+
213
+
This option is not available for builtin URIs because it does not make sense
214
+
to mirror a repository to itself.
215
+
216
+
It is possible to mirror a repository to another repository that is also
217
+
hosted by Phabricator by adding that other repository's URI, although this is
218
+
silly and probably very rarely of any use.
219
+
220
+
**None**: Phabricator will not fetch changes from or push changes to this URI.
221
+
For builtin URIs, it will not let users fetch changes from or push changes to
222
+
this URI.
223
+
224
+
You can use this mode to turn off an Observe URI after an import, stop a Mirror
225
+
URI from updating, or to add URIs that you're only using to customize which
226
+
clone URIs are displayed to the user but don't want Phabricator to interact
227
+
with directly.
228
+
229
+
**Read Only**: Phabricator will serve the repository from this URI in read-only
230
+
mode. Users will be able to fetch from it but will not be able to push to it.
231
+
232
+
Because Phabricator must be able to serve the repository from URIs configured
233
+
in this mode, this option is only available for builtin URIs.
234
+
235
+
**Read/Write**: Phabricator will serve the repository from this URI in
236
+
read/write mode. Users will be able to fetch from it and push to it.
237
+
238
+
URIs can not be set into this mode if another URI is set to //Observe// mode,
239
+
because that would mean the repository had two different authorities: the
240
+
observed remote copy and the hosted local copy. Take the other URI out of
241
+
//Observe// mode first.
242
+
243
+
Because Phabricator must be able to serve the repository from URIs configured
244
+
in this mode, this option is only available for builtin URIs.
245
+
246
+
247
+
Reference: Display Types
248
+
========================
249
+
250
+
This section details the available **Display Type** options for URIs.
251
+
252
+
**Default**: Phabricator will guess the correct option for the URI. It
253
+
guesses based on the configured **I/O Type** and whether the URI is
254
+
**builtin** or not.
255
+
256
+
For //Observe//, //Mirror// and //None// URIs, the default is //Never//.
257
+
258
+
For builtin URIs in //Read Only// or //Read/Write// mode, the most
259
+
human-readable URI defaults to //Always// and the others default to //Never//.
260
+
261
+
**Always**: This URI will be shown to users as a clone/checkout URI. You can
262
+
add URIs in this mode to cutomize exactly what users are shown.
263
+
264
+
**Never**: This URI will not be shown to users. You can hide less-preferred
265
+
URIs to guide users to the URIs they should be using to interact with the
266
+
repository.
267
+
268
+
269
+
Next Steps
270
+
==========
271
+
272
+
Continue by:
273
+
274
+
- configuring Phabricator to host repositories with
275
+
@{article:Diffusion User Guide: Repository Hosting}.