[PATCH 06 of 14] docs/usage: rework section on non-changeable repository URLs
Thomas De Schampheleire
patrickdepinguin at gmail.com
Mon Apr 6 15:12:00 EDT 2015
# HG changeset patch
# User Thomas De Schampheleire <thomas.de.schampheleire at gmail.com>
# Date 1428175740 -7200
# Sat Apr 04 21:29:00 2015 +0200
# Node ID 4fea222af02fbfbd876a79f203d48650cc20e9bc
# Parent f490e9de73ac48f9945fc49d862556d0a5034c1e
docs/usage: rework section on non-changeable repository URLs
diff --git a/docs/usage/general.rst b/docs/usage/general.rst
@@ -70,31 +70,32 @@
(and its ancestors) by selecting it and clicking the ``Open new pull request
for selected changesets`` button.
-Non changeable repository urls
+Non-changeable repository URLs
Due to the complicated nature of repository grouping, URLs of repositories
-can often change.
+can often change. For example, a repository originally accessible from::
- # after insertion to test_group group the url will be
+would get a new URL after moving it to test_group::
-This can be an issue for build systems and any other hardcoded scripts, moving
-a repository to a group leads to a need for changing external systems. To
-overcome this Kallithea introduces a non-changable replacement URL. It's
-simply a repository ID prefixed with ``_``. The above URLs are also accessible as::
+Such moving of a repository to a group can be an issue for build systems and
+other scripts where the repository paths are hardcoded. To overcome this,
+Kallithea introduces a non-changeable replacement URL, based on a repository ID
+prefixed with an underscore. In all Kallithea URLs, for example those for the
+changelog and the file view, a repository name can be replaced by this ``_ID``
+string. Since IDs are always the same, moving the repository to a different
+group will not affect such URLs.
+In the example, the repository could also be accessible as::
-Since IDs are always the same, moving the repository will not affect
-such a URL. the ``_<ID>`` syntax can be used anywhere in the system so
-URLs with ``repo_name`` for changelogs and files can be exchanged
-with the ``_<ID>`` syntax.
+The ID of a given repository can be shown from the repository ``Summary`` page,
+by selecting the ``Show by ID`` button next to the ``Clone URL``.
More information about the kallithea-general