Changeset View
Changeset View
Standalone View
Standalone View
src/docs/user/userguide/diffusion_managing.diviner
Show All 31 Lines | |||||
information (primarily callsigns and short names) gives you control over | information (primarily callsigns and short names) gives you control over | ||||
repository identifiers. | repository identifiers. | ||||
Basics: Callsigns | Basics: Callsigns | ||||
================= | ================= | ||||
Each repository can optionally be identified by a "callsign", which is a short | Each repository can optionally be identified by a "callsign", which is a short | ||||
uppercase string like "P" (for Phabricator) or "ARC" (for Arcanist). | uppercase string like "P" (for Phorge) or "ARC" (for Arcanist). | ||||
The primary goal of callsigns is to namespace commits to SVN repositories: if | The primary goal of callsigns is to namespace commits to SVN repositories: if | ||||
you use multiple SVN repositories, each repository has a revision 1, revision 2, | you use multiple SVN repositories, each repository has a revision 1, revision 2, | ||||
etc., so referring to them by number alone is ambiguous. | etc., so referring to them by number alone is ambiguous. | ||||
However, even for Git and Mercurial they impart additional information to human | However, even for Git and Mercurial they impart additional information to human | ||||
readers and allow parsers to detect that something is a commit name with high | readers and allow parsers to detect that something is a commit name with high | ||||
probability (and allow distinguishing between multiple copies of a repository). | probability (and allow distinguishing between multiple copies of a repository). | ||||
Configuring a callsign can make interacting with a commonly-used repository | Configuring a callsign can make interacting with a commonly-used repository | ||||
easier, but you may not want to bother assigning one to every repository if you | easier, but you may not want to bother assigning one to every repository if you | ||||
have some similar, templated, or rarely-used repositories. | have some similar, templated, or rarely-used repositories. | ||||
If you choose to assign a callsign to a repository, it must be unique within an | If you choose to assign a callsign to a repository, it must be unique within an | ||||
install but do not need to be globally unique, so you are free to use the | install but do not need to be globally unique, so you are free to use the | ||||
single-letter callsigns for brevity. For example, Facebook uses "E" for the | single-letter callsigns for brevity. For example, Facebook uses "E" for the | ||||
Engineering repository, "O" for the Ops repository, "Y" for a Yum package | Engineering repository, "O" for the Ops repository, "Y" for a Yum package | ||||
repository, and so on, while Phabricator uses "P" and Arcanist uses "ARC". | repository, and so on, while Phorge uses "P" and Arcanist uses "ARC". | ||||
Keeping callsigns brief will make them easier to use, and the use of | Keeping callsigns brief will make them easier to use, and the use of | ||||
one-character callsigns is encouraged if they are reasonably evocative. | one-character callsigns is encouraged if they are reasonably evocative. | ||||
If you configure a callsign like `XYZ`, Phabricator will activate callsign URIs | If you configure a callsign like `XYZ`, Phorge will activate callsign URIs | ||||
and activate the callsign identifier (like `rXYZ`) for the repository. These | and activate the callsign identifier (like `rXYZ`) for the repository. These | ||||
more human-readable identifiers can make things a little easier to interact | more human-readable identifiers can make things a little easier to interact | ||||
with. | with. | ||||
Basics: Short Name | Basics: Short Name | ||||
================== | ================== | ||||
Show All 28 Lines | |||||
Before content from the repository can be shown in the web UI or embedded in | Before content from the repository can be shown in the web UI or embedded in | ||||
other contexts like email, it must be converted to UTF-8. | other contexts like email, it must be converted to UTF-8. | ||||
Most source code is written in UTF-8 or a subset of UTF-8 (like plain ASCII) | Most source code is written in UTF-8 or a subset of UTF-8 (like plain ASCII) | ||||
already, so everything will work fine. The majority of repositories do not need | already, so everything will work fine. The majority of repositories do not need | ||||
to adjust this setting. | to adjust this setting. | ||||
If your repository is primarily written in some other encoding, specify it here | If your repository is primarily written in some other encoding, specify it here | ||||
so Phabricator can convert from it properly when reading content to embed in | so Phorge can convert from it properly when reading content to embed in | ||||
a webpage or email. | a webpage or email. | ||||
Basics: Dangerous Changes | Basics: Dangerous Changes | ||||
========================= | ========================= | ||||
By default, repositories are protected against dangerous changes. Dangerous | By default, repositories are protected against dangerous changes. Dangerous | ||||
changes are operations which rewrite or destroy repository history (for | changes are operations which rewrite or destroy repository history (for | ||||
Show All 10 Lines | |||||
If you fully disable this at the repository level, you can still use Herald to | If you fully disable this at the repository level, you can still use Herald to | ||||
selectively protect certain branches or grant this power to a limited set of | selectively protect certain branches or grant this power to a limited set of | ||||
users. | users. | ||||
This option is only available in Git and Mercurial, because it is impossible | This option is only available in Git and Mercurial, because it is impossible | ||||
to make dangerous changes in Subversion. | to make dangerous changes in Subversion. | ||||
This option has no effect if a repository is not hosted because Phabricator | This option has no effect if a repository is not hosted because Phorge | ||||
can not prevent dangerous changes in a remote repository it is merely | can not prevent dangerous changes in a remote repository it is merely | ||||
observing. | observing. | ||||
Basics: Disable Publishing | Basics: Disable Publishing | ||||
========================== | ========================== | ||||
You can disable publishing for a repository. For more details on what this | You can disable publishing for a repository. For more details on what this | ||||
▲ Show 20 Lines • Show All 47 Lines • ▼ Show 20 Lines | |||||
You can configure granular access policies for each repository to control who | You can configure granular access policies for each repository to control who | ||||
can view, clone, administrate, and push to the repository. | can view, clone, administrate, and push to the repository. | ||||
Policies: View | Policies: View | ||||
============== | ============== | ||||
The view policy for a repository controls who can view the repository from | The view policy for a repository controls who can view the repository from | ||||
the web UI and clone, fetch, or check it out from Phabricator. | the web UI and clone, fetch, or check it out from Phorge. | ||||
Users who can view a repository can also access the "Manage" interface to | Users who can view a repository can also access the "Manage" interface to | ||||
review information about the repository and examine the edit history, but can | review information about the repository and examine the edit history, but can | ||||
not make any changes. | not make any changes. | ||||
Policies: Edit | Policies: Edit | ||||
============== | ============== | ||||
The edit policy for a repository controls who can change repository settings | The edit policy for a repository controls who can change repository settings | ||||
using the "Manage" interface. In essence, this is permission to administrate | using the "Manage" interface. In essence, this is permission to administrate | ||||
the repository. | the repository. | ||||
You must be able to view a repository to edit it. | You must be able to view a repository to edit it. | ||||
You do not need this permission to push changes to a repository. | You do not need this permission to push changes to a repository. | ||||
Policies: Push | Policies: Push | ||||
============== | ============== | ||||
The push policy for a repository controls who can push changes to the | The push policy for a repository controls who can push changes to the | ||||
repository. | repository. | ||||
This policy has no effect if Phabricator is not hosting the repository, because | This policy has no effect if Phorge is not hosting the repository, because | ||||
it can not control who is allowed to make changes to a remote repository it is | it can not control who is allowed to make changes to a remote repository it is | ||||
merely observing. | merely observing. | ||||
You must also be able to view a repository to push to it. | You must also be able to view a repository to push to it. | ||||
You do not need to be able to edit a repository to push to it. | You do not need to be able to edit a repository to push to it. | ||||
Further restrictions on who can push (and what they can push) can be configured | Further restrictions on who can push (and what they can push) can be configured | ||||
for hosted repositories with Herald, which allows you to write more | for hosted repositories with Herald, which allows you to write more | ||||
sophisticated rules that evaluate when Phabricator receives a push. To get | sophisticated rules that evaluate when Phorge receives a push. To get | ||||
started with Herald, see @{article:Herald User Guide}. | started with Herald, see @{article:Herald User Guide}. | ||||
Additionally, Git and Mercurial repositories have a setting which allows | Additionally, Git and Mercurial repositories have a setting which allows | ||||
you to **Prevent Dangerous Changes**. This setting is enabled by default and | you to **Prevent Dangerous Changes**. This setting is enabled by default and | ||||
will prevent any users from pushing changes which rewrite or destroy history. | will prevent any users from pushing changes which rewrite or destroy history. | ||||
URIs | URIs | ||||
==== | ==== | ||||
The **URIs** panel allows you to add and manage URIs which Phabricator will | The **URIs** panel allows you to add and manage URIs which Phorge will | ||||
fetch from, serve from, and push to. | fetch from, serve from, and push to. | ||||
These options are covered in detail in @{article:Diffusion User Guide: URIs}. | These options are covered in detail in @{article:Diffusion User Guide: URIs}. | ||||
Limits | Limits | ||||
====== | ====== | ||||
Show All 34 Lines | |||||
10,000 files in a single commit, but will reject users mistakenly trying to | 10,000 files in a single commit, but will reject users mistakenly trying to | ||||
push a copy of another repository or a directory with a million logfiles or | push a copy of another repository or a directory with a million logfiles or | ||||
whatever other kind of creative nonsense they manage to dream up. | whatever other kind of creative nonsense they manage to dream up. | ||||
Branches | Branches | ||||
======== | ======== | ||||
The **Branches** panel allows you to configure how Phabricator interacts with | The **Branches** panel allows you to configure how Phorge interacts with | ||||
branches. | branches. | ||||
This panel is not available for Subversion repositories, because Subversion | This panel is not available for Subversion repositories, because Subversion | ||||
does not have formal branches. | does not have formal branches. | ||||
You can configure a **Default Branch**. This controls which branch is shown by | You can configure a **Default Branch**. This controls which branch is shown by | ||||
default in the UI. If no branch is provided, Phabricator will use `master` in | default in the UI. If no branch is provided, Phorge will use `master` in | ||||
Git and `default` in Mercurial. | Git and `default` in Mercurial. | ||||
**Fetch Refs**: In Git, if you are observing a remote repository, you can | **Fetch Refs**: In Git, if you are observing a remote repository, you can | ||||
specify that you only want to fetch a subset of refs using "Fetch Refs". | specify that you only want to fetch a subset of refs using "Fetch Refs". | ||||
Normally, all refs (`refs/*`) are fetched. This means all branches, all tags, | Normally, all refs (`refs/*`) are fetched. This means all branches, all tags, | ||||
and all other refs. | and all other refs. | ||||
If you want to fetch only a few specific branches, you can list only those | If you want to fetch only a few specific branches, you can list only those | ||||
branches. For example, this will fetch only the branch "master": | branches. For example, this will fetch only the branch "master": | ||||
``` | ``` | ||||
refs/heads/master | refs/heads/master | ||||
``` | ``` | ||||
You can fetch all branches and tags (but ignore other refs) like this: | You can fetch all branches and tags (but ignore other refs) like this: | ||||
``` | ``` | ||||
refs/heads/* | refs/heads/* | ||||
refs/tags/* | refs/tags/* | ||||
``` | ``` | ||||
This may be useful if the remote is on a service like GitHub, GitLab, or | This may be useful if the remote is on a service like GitHub, GitLab, or | ||||
Gerrit and uses custom refs (like `refs/pull/` or `refs/changes/`) to store | Gerrit and uses custom refs (like `refs/pull/` or `refs/changes/`) to store | ||||
metadata that you don't want to bring into Phabricator. | metadata that you don't want to bring into Phorge. | ||||
**Permanent Refs**: To learn more about permanent refs, see: | **Permanent Refs**: To learn more about permanent refs, see: | ||||
- @{article:Diffusion User Guide: Permanent Refs} | - @{article:Diffusion User Guide: Permanent Refs} | ||||
By default, Phabricator considers all branches to be permanent refs. If you | By default, Phorge considers all branches to be permanent refs. If you | ||||
only want some branches to be treated as permanent refs, specify them here. | only want some branches to be treated as permanent refs, specify them here. | ||||
When specifying branches, you should enter one branch name per line. You can | When specifying branches, you should enter one branch name per line. You can | ||||
use regular expressions to match branches by wrapping an expression in | use regular expressions to match branches by wrapping an expression in | ||||
`regexp(...)`. For example: | `regexp(...)`. For example: | ||||
| Example | Effect | | | Example | Effect | | ||||
|---------|--------| | |---------|--------| | ||||
Show All 9 Lines | |||||
changes available to build and continuous integration systems. | changes available to build and continuous integration systems. | ||||
For more details, see @{article:Harbormaster User Guide}. | For more details, see @{article:Harbormaster User Guide}. | ||||
Automation | Automation | ||||
========== | ========== | ||||
The **Automation** panel configures support for allowing Phabricator to make | The **Automation** panel configures support for allowing Phorge to make | ||||
writes directly to the repository, so that it can perform operations like | writes directly to the repository, so that it can perform operations like | ||||
automatically landing revisions from the web UI. | automatically landing revisions from the web UI. | ||||
For details on repository automation, see | For details on repository automation, see | ||||
@{article:Drydock User Guide: Repository Automation}. | @{article:Drydock User Guide: Repository Automation}. | ||||
Symbols | Symbols | ||||
Show All 27 Lines | - A **callsign** identifier, like `rXY`. This is available for repositories | ||||
with a callsign. | with a callsign. | ||||
- A **short name** identifier, like `xylophone`. This is available for | - A **short name** identifier, like `xylophone`. This is available for | ||||
repositories with a short name. | repositories with a short name. | ||||
All three identifiers can be used to refer to the repository in cases where | All three identifiers can be used to refer to the repository in cases where | ||||
the intent is unambiguous, but only the first two forms work in ambiguous | the intent is unambiguous, but only the first two forms work in ambiguous | ||||
contexts. | contexts. | ||||
For example, if you type `R123` or `rXY` into a comment, Phabricator will | For example, if you type `R123` or `rXY` into a comment, Phorge will | ||||
recognize them as references to the repository. If you type `xylophone`, it | recognize them as references to the repository. If you type `xylophone`, it | ||||
assumes you mean the word "xylophone". | assumes you mean the word "xylophone". | ||||
Only the `R123` identifier is immutable: the others can be changed later by | Only the `R123` identifier is immutable: the others can be changed later by | ||||
adjusting the callsign or short name for the repository. | adjusting the callsign or short name for the repository. | ||||
Commit Identifiers | Commit Identifiers | ||||
================== | ================== | ||||
Diffusion uses repository identifiers and information about the commit itself | Diffusion uses repository identifiers and information about the commit itself | ||||
to generate globally unique identifiers for each commit, like `rE12345`. | to generate globally unique identifiers for each commit, like `rE12345`. | ||||
Each commit may have several identifiers: | Each commit may have several identifiers: | ||||
- A repository **ID** identifier, like `R123:abcdef123...`. | - A repository **ID** identifier, like `R123:abcdef123...`. | ||||
- A repository **callsign** identifier, like `rXYZabcdef123...`. This only | - A repository **callsign** identifier, like `rXYZabcdef123...`. This only | ||||
works if a repository has a callsign. | works if a repository has a callsign. | ||||
- Any unique prefix of the commit hash. | - Any unique prefix of the commit hash. | ||||
Git and Mercurial use commit hashes to identify commits, and Phabricator will | Git and Mercurial use commit hashes to identify commits, and Phorge will | ||||
recognize a commit if the hash prefix is unique and sufficiently long. Commit | recognize a commit if the hash prefix is unique and sufficiently long. Commit | ||||
hashes qualified with a repository identifier must be at least 5 characters | hashes qualified with a repository identifier must be at least 5 characters | ||||
long; unqualified commit hashes must be at least 7 characters long. | long; unqualified commit hashes must be at least 7 characters long. | ||||
In Subversion, commit identifiers are sequential integers and prefixes can not | In Subversion, commit identifiers are sequential integers and prefixes can not | ||||
be used to identify them. | be used to identify them. | ||||
When rendering the name of a Git or Mercurial commit hash, Phabricator tends to | When rendering the name of a Git or Mercurial commit hash, Phorge tends to | ||||
shorten it to 12 characters. This "short length" is relatively long compared to | shorten it to 12 characters. This "short length" is relatively long compared to | ||||
Git itself (which often uses 7 characters). See this post on the LKML for a | Git itself (which often uses 7 characters). See this post on the LKML for a | ||||
historical explanation of Git's occasional internal use of 7-character hashes: | historical explanation of Git's occasional internal use of 7-character hashes: | ||||
https://lkml.org/lkml/2010/10/28/287 | https://lkml.org/lkml/2010/10/28/287 | ||||
Because 7-character hashes are likely to collide for even moderately large | Because 7-character hashes are likely to collide for even moderately large | ||||
repositories, Diffusion generally uses either a 12-character prefix (which makes | repositories, Diffusion generally uses either a 12-character prefix (which makes | ||||
Show All 10 Lines |
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