Differential D25007 Diff 23 src/docs/user/userguide/diffusion_uris.diviner

Changeset View

Standalone View

src/docs/user/userguide/diffusion_uris.diviner

@title Diffusion User Guide: URIs		@title Diffusion User Guide: URIs
@group userguide		@group userguide

Guide to configuring repository URIs for fetching, cloning and mirroring.		Guide to configuring repository URIs for fetching, cloning and mirroring.

Overview		Overview
========		========

Phabricator can create, host, observe, mirror, proxy, and import repositories.		Phorge can create, host, observe, mirror, proxy, and import repositories.
For example, you can:		For example, you can:

Host Repositories: Phabricator can host repositories locally. Phabricator		Host Repositories: Phorge can host repositories locally. Phorge
maintains the writable master version of the repository, and you can push and		maintains the writable master version of the repository, and you can push and
pull the repository. This is the most straightforward kind of repository		pull the repository. This is the most straightforward kind of repository
configuration, and similar to repositories on other services like GitHub or		configuration, and similar to repositories on other services like GitHub or
Bitbucket.		Bitbucket.

Observe Repositories: Phabricator can create a copy of an repository which		Observe Repositories: Phorge can create a copy of an repository which
is hosted elsewhere (like GitHub or Bitbucket) and track updates to the remote		is hosted elsewhere (like GitHub or Bitbucket) and track updates to the remote
repository. This will create a read-only copy of the repository in Phabricator.		repository. This will create a read-only copy of the repository in Phorge.

Mirror Repositories: Phabricator can publish any repository to mirrors,		Mirror Repositories: Phorge can publish any repository to mirrors,
overwriting them with an exact copy of the repository that stays up to date as		overwriting them with an exact copy of the repository that stays up to date as
the source changes. This works with both local repositories that Phabricator is		the source changes. This works with both local repositories that Phorge is
hosting and remote repositories that Phabricator is observing.		hosting and remote repositories that Phorge is observing.

Proxy Repositories: If you are observing a repository, you can allow users		Proxy Repositories: If you are observing a repository, you can allow users
to read Phabricator's copy of the repository. Phabricator supports granular		to read Phorge's copy of the repository. Phorge supports granular
read permissions, so this can let you open a private repository up a little		read permissions, so this can let you open a private repository up a little
bit in a flexible way.		bit in a flexible way.

Import Repositories: If you have a repository elsewhere that you want to		Import Repositories: If you have a repository elsewhere that you want to
host on Phabricator, you can observe the remote repository first, then turn		host on Phorge, you can observe the remote repository first, then turn
the tracking off once the repository fully synchronizes. This allows you to		the tracking off once the repository fully synchronizes. This allows you to
copy an existing repository and begin hosting it in Phabricator.		copy an existing repository and begin hosting it in Phorge.

You can also import repositories by creating an empty hosted repository and		You can also import repositories by creating an empty hosted repository and
then pushing everything to the repository directly.		then pushing everything to the repository directly.

You configure the behavior of a Phabricator repository by adding and		You configure the behavior of a Phorge repository by adding and
configuring URIs and marking them to be fetched from, mirrored to, clonable,		configuring URIs and marking them to be fetched from, mirrored to, clonable,
and so on. By configuring all the URIs that a repository should interact with		and so on. By configuring all the URIs that a repository should interact with
and expose to users, you configure the read, write, and mirroring behavior		and expose to users, you configure the read, write, and mirroring behavior
of the repository.		of the repository.

The remainder of this document walks through this configuration in greater		The remainder of this document walks through this configuration in greater
detail.		detail.


Host a Repository		Host a Repository
=================		=================

You can create new repositories that Phabricator will host, like you would		You can create new repositories that Phorge will host, like you would
create repositories on services like GitHub or Bitbucket. Phabricator will		create repositories on services like GitHub or Bitbucket. Phorge will
serve a read-write copy of the repository and you can clone it from Phabricator		serve a read-write copy of the repository and you can clone it from Phorge
and push changes to Phabricator.		and push changes to Phorge.

If you haven't already, you may need to configure Phabricator for hosting		If you haven't already, you may need to configure Phorge for hosting
before you can create your first hosted repository. For a detailed guide,		before you can create your first hosted repository. For a detailed guide,
see @{article:Diffusion User Guide: Repository Hosting}.		see @{article:Diffusion User Guide: Repository Hosting}.

This is the default mode for new repositories. To host a repository:		This is the default mode for new repositories. To host a repository:

- Create a new repository.		- Create a new repository.
- Activate it.		- Activate it.

Phabricator will create an empty repository and allow you to fetch from it and		Phorge will create an empty repository and allow you to fetch from it and
push to it.		push to it.


Observe a Repository		Observe a Repository
====================		====================

If you have an existing repository hosted on another service (like GitHub,		If you have an existing repository hosted on another service (like GitHub,
Bitbucket, or a private server) that you want to work with in Phabricator,		Bitbucket, or a private server) that you want to work with in Phorge,
you can configure Phabricator to observe it.		you can configure Phorge to observe it.

When observing a repository, Phabricator will keep track of changes in the		When observing a repository, Phorge will keep track of changes in the
remote repository and allow you to browse and interact with the repository from		remote repository and allow you to browse and interact with the repository from
the web UI in Diffusion and other applications, but you can continue hosting it		the web UI in Diffusion and other applications, but you can continue hosting it
elsewhere.		elsewhere.

To observe a repository:		To observe a repository:

- Create a new repository, but don't activate it yet.		- Create a new repository, but don't activate it yet.
- Add the remote URI you want to observe as a repository URI.		- Add the remote URI you want to observe as a repository URI.
- Set the I/O Type for the URI to Observe.		- Set the I/O Type for the URI to Observe.
- If necessary, configure a credential.		- If necessary, configure a credential.
- Activate the repository.		- Activate the repository.

Phabricator will perform an initial import of the repository, creating a local		Phorge will perform an initial import of the repository, creating a local
read-only copy. Once this process completes, it will continue keeping track of		read-only copy. Once this process completes, it will continue keeping track of
changes in the remote, fetching them, and reflecting them in the UI.		changes in the remote, fetching them, and reflecting them in the UI.


Mirror a Repository		Mirror a Repository
===================		===================

NOTE: Mirroring is not supported in Subversion.		NOTE: Mirroring is not supported in Subversion.

You can create a read-only mirror of an existing repository. Phabricator will		You can create a read-only mirror of an existing repository. Phorge will
continuously publish the state of the source repository to the mirror, creating		continuously publish the state of the source repository to the mirror, creating
an exact copy.		an exact copy.

For example, if you have a repository hosted in Phabricator that you want to		For example, if you have a repository hosted in Phorge that you want to
mirror to GitHub, you can configure Phabricator to automatically maintain the		mirror to GitHub, you can configure Phorge to automatically maintain the
mirror. This is how the upstream repositories are set up.		mirror. This is how the upstream repositories are set up.

The mirror copy must be read-only for users because any writes made to the		The mirror copy must be read-only for users because any writes made to the
mirror will be undone when Phabricator updates it. The mirroring process copies		mirror will be undone when Phorge updates it. The mirroring process copies
the entire repository state exactly, so the remote state will be completely		the entire repository state exactly, so the remote state will be completely
replaced with an exact copy of the source repository. This may remove or		replaced with an exact copy of the source repository. This may remove or
destroy information. Normally, you should only mirror to an empty repository.		destroy information. Normally, you should only mirror to an empty repository.

You can mirror any repository, even if Phabricator is only observing it and not		You can mirror any repository, even if Phorge is only observing it and not
hosting it directly.		hosting it directly.

To begin mirroring a repository:		To begin mirroring a repository:

- Create a hosted or observed repository by following the relevant		- Create a hosted or observed repository by following the relevant
instructions above.		instructions above.
- Add the remote URI you want to mirror to as a repository URI.		- Add the remote URI you want to mirror to as a repository URI.
- Set the I/O Type for the URI to Mirror.		- Set the I/O Type for the URI to Mirror.
- If necessary, configure a credential.		- If necessary, configure a credential.

To stop mirroring:		To stop mirroring:

- Disable the mirror URI; or		- Disable the mirror URI; or
- Change the I/O Type for the URI to None.		- Change the I/O Type for the URI to None.


Import a Repository		Import a Repository
===================		===================

If you have an existing repository that you want to move so it is hosted on		If you have an existing repository that you want to move so it is hosted on
Phabricator, there are three ways to do it:		Phorge, there are three ways to do it:

Observe First: //(Git, Mercurial)// Observe the existing repository first,		Observe First: //(Git, Mercurial)// Observe the existing repository first,
according to the instructions above. Once Phabricator's copy of the repository		according to the instructions above. Once Phorge's copy of the repository
is fully synchronized, change the I/O Type for the Observe URI to		is fully synchronized, change the I/O Type for the Observe URI to
None to stop fetching changes from the remote.		None to stop fetching changes from the remote.

By default, this will automatically make Phabricator's copy of the repository		By default, this will automatically make Phorge's copy of the repository
writable, and you can begin pushing to it. If you've adjusted URI		writable, and you can begin pushing to it. If you've adjusted URI
configuration away from the defaults, you may need to set at least one URI		configuration away from the defaults, you may need to set at least one URI
to Read/Write mode so you can push to it.		to Read/Write mode so you can push to it.

Push Everything: //(Git, Mercurial, Subversion)// Create a new empty hosted		Push Everything: //(Git, Mercurial, Subversion)// Create a new empty hosted
repository according to the instructions above. Once the empty repository		repository according to the instructions above. Once the empty repository
initializes, push your entire existing repository to it.		initializes, push your entire existing repository to it.

Show All 12 Lines

Once you've put a working copy in the right place on disk, activate the		Once you've put a working copy in the right place on disk, activate the
repository.		repository.


Builtin Clone URIs		Builtin Clone URIs
==================		==================

By default, Phabricator automatically exposes and activates HTTP, HTTPS and		By default, Phorge automatically exposes and activates HTTP, HTTPS and
SSH clone URIs by examining configuration.		SSH clone URIs by examining configuration.

HTTP: The `http://` clone URI will be available if these conditions are		HTTP: The `http://` clone URI will be available if these conditions are
satisfied:		satisfied:

- `diffusion.allow-http-auth` must be enabled or the repository view policy		- `diffusion.allow-http-auth` must be enabled or the repository view policy
must be "Public".		must be "Public".
- The repository must be a Git or Mercurial repository.		- The repository must be a Git or Mercurial repository.
Show All 12 Lines	conditions are satisfied:

- `phd.user` must be configured.		- `phd.user` must be configured.


Customizing Displayed Clone URIs		Customizing Displayed Clone URIs
================================		================================

If you have an unusual configuration and want the UI to offers users specific		If you have an unusual configuration and want the UI to offers users specific
clone URIs other than the URIs that Phabricator serves or interacts with, you		clone URIs other than the URIs that Phorge serves or interacts with, you
can add those URIs with the I/O Type set to None and then set their		can add those URIs with the I/O Type set to None and then set their
Display Type to Always.		Display Type to Always.

Likewise, you can set the Display Type of any URIs you do //not// want		Likewise, you can set the Display Type of any URIs you do //not// want
to be visible to Never.		to be visible to Never.

This allows you to precisely configure which clone URIs are shown to users for		This allows you to precisely configure which clone URIs are shown to users for
a repository.		a repository.


Reference: I/O Types		Reference: I/O Types
====================		====================

This section details the available I/O Type options for URIs.		This section details the available I/O Type options for URIs.

Each repository has some builtin URIs. These are URIs hosted by Phabricator		Each repository has some builtin URIs. These are URIs hosted by Phorge
itself. The modes available for each URI depend primarily on whether it is a		itself. The modes available for each URI depend primarily on whether it is a
builtin URI or not.		builtin URI or not.

Default: This setting has Phabricator guess the correct option for the		Default: This setting has Phorge guess the correct option for the
URI.		URI.

For builtin URIs, the default behavior is //Read/Write// if the repository		For builtin URIs, the default behavior is //Read/Write// if the repository
is hosted, and //Read-Only// if the repository is observed.		is hosted, and //Read-Only// if the repository is observed.

For custom URIs, the default type is //None// because we can not automatically		For custom URIs, the default type is //None// because we can not automatically
guess if you want to ignore, observe, or mirror a URI and //None// is the		guess if you want to ignore, observe, or mirror a URI and //None// is the
safest default.		safest default.

Observe: Phabricator will observe this repository and regularly fetch any		Observe: Phorge will observe this repository and regularly fetch any
changes made to it to a local read-only copy.		changes made to it to a local read-only copy.

You can not observe builtin URIs because reading a repository from itself		You can not observe builtin URIs because reading a repository from itself
does not make sense.		does not make sense.

You can not add a URI in Observe mode if an existing builtin URI is in		You can not add a URI in Observe mode if an existing builtin URI is in
//Read/Write// mode, because this would mean the repository had two different		//Read/Write// mode, because this would mean the repository had two different
authorities: the observed remote copy and the hosted local copy. Take the		authorities: the observed remote copy and the hosted local copy. Take the
other URI out of //Read/Write// mode first.		other URI out of //Read/Write// mode first.

WARNING: If you observe a remote repository, the entire state of the working		WARNING: If you observe a remote repository, the entire state of the working
copy that Phabricator maintains will be deleted and replaced with the state of		copy that Phorge maintains will be deleted and replaced with the state of
the remote. If some changes are present only in Phabricator's working copy,		the remote. If some changes are present only in Phorge's working copy,
they will be unrecoverably destroyed.		they will be unrecoverably destroyed.

Mirror: Phabricator will push any changes made to this repository to the		Mirror: Phorge will push any changes made to this repository to the
remote URI, keeping a read-only mirror hosted at that URI up to date.		remote URI, keeping a read-only mirror hosted at that URI up to date.

This works for both observed and hosted repositories.		This works for both observed and hosted repositories.

This option is not available for builtin URIs because it does not make sense		This option is not available for builtin URIs because it does not make sense
to mirror a repository to itself.		to mirror a repository to itself.

It is possible to mirror a repository to another repository that is also		It is possible to mirror a repository to another repository that is also
hosted by Phabricator by adding that other repository's URI, although this is		hosted by Phorge by adding that other repository's URI, although this is
silly and probably very rarely of any use.		silly and probably very rarely of any use.

WARNING: If you mirror to a remote repository, the entire state of that remote		WARNING: If you mirror to a remote repository, the entire state of that remote
will be replaced with the state of the working copy Phabricator maintains. If		will be replaced with the state of the working copy Phorge maintains. If
some changes are present only in the remote, they will be unrecoverably		some changes are present only in the remote, they will be unrecoverably
destroyed.		destroyed.

None: Phabricator will not fetch changes from or push changes to this URI.		None: Phorge will not fetch changes from or push changes to this URI.
For builtin URIs, it will not let users fetch changes from or push changes to		For builtin URIs, it will not let users fetch changes from or push changes to
this URI.		this URI.

You can use this mode to turn off an Observe URI after an import, stop a Mirror		You can use this mode to turn off an Observe URI after an import, stop a Mirror
URI from updating, or to add URIs that you're only using to customize which		URI from updating, or to add URIs that you're only using to customize which
clone URIs are displayed to the user but don't want Phabricator to interact		clone URIs are displayed to the user but don't want Phorge to interact
with directly.		with directly.

Read Only: Phabricator will serve the repository from this URI in read-only		Read Only: Phorge will serve the repository from this URI in read-only
mode. Users will be able to fetch from it but will not be able to push to it.		mode. Users will be able to fetch from it but will not be able to push to it.

Because Phabricator must be able to serve the repository from URIs configured		Because Phorge must be able to serve the repository from URIs configured
in this mode, this option is only available for builtin URIs.		in this mode, this option is only available for builtin URIs.

Read/Write: Phabricator will serve the repository from this URI in		Read/Write: Phorge will serve the repository from this URI in
read/write mode. Users will be able to fetch from it and push to it.		read/write mode. Users will be able to fetch from it and push to it.

URIs can not be set into this mode if another URI is set to //Observe// mode,		URIs can not be set into this mode if another URI is set to //Observe// mode,
because that would mean the repository had two different authorities: the		because that would mean the repository had two different authorities: the
observed remote copy and the hosted local copy. Take the other URI out of		observed remote copy and the hosted local copy. Take the other URI out of
//Observe// mode first.		//Observe// mode first.

Because Phabricator must be able to serve the repository from URIs configured		Because Phorge must be able to serve the repository from URIs configured
in this mode, this option is only available for builtin URIs.		in this mode, this option is only available for builtin URIs.


Reference: Display Types		Reference: Display Types
========================		========================

This section details the available Display Type options for URIs.		This section details the available Display Type options for URIs.

Default: Phabricator will guess the correct option for the URI. It		Default: Phorge will guess the correct option for the URI. It
guesses based on the configured I/O Type and whether the URI is		guesses based on the configured I/O Type and whether the URI is
builtin or not.		builtin or not.

For //Observe//, //Mirror// and //None// URIs, the default is //Never//.		For //Observe//, //Mirror// and //None// URIs, the default is //Never//.

For builtin URIs in //Read Only// or //Read/Write// mode, the most		For builtin URIs in //Read Only// or //Read/Write// mode, the most
human-readable URI defaults to //Always// and the others default to //Never//.		human-readable URI defaults to //Always// and the others default to //Never//.

Always: This URI will be shown to users as a clone/checkout URI. You can		Always: This URI will be shown to users as a clone/checkout URI. You can
add URIs in this mode to customize exactly what users are shown.		add URIs in this mode to customize exactly what users are shown.

Never: This URI will not be shown to users. You can hide less-preferred		Never: This URI will not be shown to users. You can hide less-preferred
URIs to guide users to the URIs they should be using to interact with the		URIs to guide users to the URIs they should be using to interact with the
repository.		repository.


Next Steps		Next Steps
==========		==========

Continue by:		Continue by:

- configuring Phabricator to host repositories with		- configuring Phorge to host repositories with
@{article:Diffusion User Guide: Repository Hosting}.		@{article:Diffusion User Guide: Repository Hosting}.