This is an automated email from the ASF dual-hosted git repository.
slachiewicz pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/maven-site.git
The following commit(s) were added to refs/heads/master by this push:
new 8bf14b04 Add an SCM URLs page to the POM reference
8bf14b04 is described below
commit 8bf14b04e2083030a7cbc721c11e4938fc91035a
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 20:11:34 2026 +0000
Add an SCM URLs page to the POM reference
---
content/filtered-resources/.htaccess | 4 +
content/markdown/guides/index.md.vm | 1 +
content/markdown/pom-scm-urls.md | 164 +++++++++++++++++++++++++++++++++++
content/markdown/pom.md | 12 +--
content/site.xml | 4 +-
5 files changed, 178 insertions(+), 7 deletions(-)
diff --git a/content/filtered-resources/.htaccess
b/content/filtered-resources/.htaccess
index 643a334f..7f7b0c2c 100644
--- a/content/filtered-resources/.htaccess
+++ b/content/filtered-resources/.htaccess
@@ -23,6 +23,10 @@ Redirect Permanent
/developers/release/pmc-release-process.html /developers/rele
Redirect Permanent /development-process.html
/archives/maven-1.x/development-process.html
Redirect Permanent /welcome-to-new-committers.html
/developers/welcome-to-new-committers.html
+Redirect Permanent /scm/local.html /pom-scm-urls.html#Local_file_system
+Redirect Permanent /scm/scm-url-format.html /pom-scm-urls.html
+Redirect Permanent /scm/scms-overview.html /pom-scm-urls.html#Supported_SCMs
+
Redirect Permanent /plugins/maven-checkstyle-plugin/customize.html
/plugins/maven-checkstyle-plugin/examples/custom-checker-config.html
Redirect Permanent /plugins/maven-checkstyle-plugin/howto.html
/plugins/maven-checkstyle-plugin/usage.html
Redirect Permanent /plugins/maven-checkstyle-plugin/tips.html
/plugins/maven-checkstyle-plugin/examples/multi-module-config.html
diff --git a/content/markdown/guides/index.md.vm
b/content/markdown/guides/index.md.vm
index 9a120dec..f9758de6 100644
--- a/content/markdown/guides/index.md.vm
+++ b/content/markdown/guides/index.md.vm
@@ -56,6 +56,7 @@ User Centre
- [Profiles](./introduction/introduction-to-profiles.html)
- [Configuring Plug-ins](./mini/guide-configuring-plugins.html)
- [POM Overview](../pom.html) ([Technical Project
Descriptor](../ref/current/maven-model/maven.html))
+- [SCM URLs](../pom-scm-urls.html)
- [Settings Overview](../settings.html) ([Technical Settings
Descriptor](../ref/current/maven-settings/settings.html))
Plugin Developer Centre
diff --git a/content/markdown/pom-scm-urls.md b/content/markdown/pom-scm-urls.md
new file mode 100644
index 00000000..37114a50
--- /dev/null
+++ b/content/markdown/pom-scm-urls.md
@@ -0,0 +1,164 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+
+# SCM URLs
+
+The `<connection>`, `<developerConnection>` and `<url>` elements of the
[`<scm>` section of the POM](./pom.html#SCM) tell Maven and its plugins where a
project's sources live.
+The connection elements hold an SCM URL, which [Maven SCM](/scm/) parses to
find the provider that talks to the version control system.
+This page describes the URL syntax and the SCM URL each of the standard
providers expects.
+The provider's own configuration is described on the [Maven SCM site](/scm/).
+
+<!--MACRO{toc|fromDepth=2|toDepth=3}-->
+
+## SCM URL format
+
+The general format of an SCM URL is
+
+```
+scm:<provider id><delimiter><provider-specific part>
+```
+
+The delimiter is either a colon (`:`) or a pipe (`|`).
+Use the pipe if one of the variables contains a colon, for example a Windows
path.
+
+Provider IDs may be remapped with the plugin parameter
`providerImplementations`, supported by both
[maven-release-plugin](/maven-release/maven-release-plugin/prepare-mojo.html#providerImplementations)
and
[maven-scm-plugin](/scm/maven-scm-plugin/checkout-mojo.html#providerImplementations).
+
+## Supported SCMs
+
+The following providers ship with Maven SCM.
+
+| SCM | Provider ID | Provider module | Native Java |
+|:---:|:---:|:---:|:---:|
+| [Git](#Git) | `git` | [Git Executable
Provider](/scm/maven-scm-providers/maven-scm-providers-git/maven-scm-provider-gitexe/index.html)
| no |
+| [Git](#Git) | `jgit` | [JGit
Provider](/scm/maven-scm-providers/maven-scm-providers-git/maven-scm-provider-jgit/index.html)
| yes |
+| [Subversion](#Subversion) | `svn` | [SVN Executable
Provider](/scm/maven-scm-providers/maven-scm-providers-svn/maven-scm-provider-svnexe/index.html)
| no |
+| [Mercurial](#Mercurial) | `hg` | [Mercurial (Hg)
Provider](/scm/maven-scm-providers/maven-scm-provider-hg/index.html) | no |
+| [Local](#Local_file_system) | `local` | [Local
Provider](/scm/maven-scm-providers/maven-scm-provider-local/index.html) | yes |
+
+A third-party provider,
[maven-scm-provider-svnjava](https://github.com/olamy/maven-scm-provider-svnjava),
is a native Java Subversion provider based on SVNKit.
+
+See also the [comparison of revision control
software](https://en.wikipedia.org/wiki/Comparison_of_revision_control_software)
and the [common vocabulary of source code
management](https://en.wikipedia.org/wiki/Source_Code_Management#Common_vocabulary).
+
+The examples below use a colon as the delimiter.
+
+## Git
+
+The Git providers (`git` and `jgit`) accept the following URLs. The separator
for the port is always a colon, because that part is specified in the [Git URL
specification](https://git-scm.com/docs/git-clone#_git_urls).
+
+```
+scm:git:git://server_name[:port]/path_to_repository
+scm:git:http://server_name[:port]/path_to_repository
+scm:git:https://server_name[:port]/path_to_repository
+scm:git:ssh://server_name[:port]/path_to_repository
+scm:git:file://[hostname]/path_to_repository
+```
+
+The SSH protocol also has an SCP-like syntax in which the protocol is left out:
+
+```
+scm:git:[<user>@]<host>:/<path-to-git-repo>
+```
+
+GitHub proposes this form by default, without the leading slash:
+
+```
+scm:git:[<user>@]<host>:<path-to-git-repo>
+```
+
+For example:
+
+```
+scm:git:git://github.com/path_to_repository
+scm:git:http://github.com/path_to_repository
+scm:git:https://github.com/path_to_repository
+scm:git:[email protected]:path_to_repository
+scm:git:ssh://github.com/path_to_repository
+scm:git:file://localhost/path_to_repository
+```
+
+### Different fetch and push URLs
+
+Sometimes read and write operations need different URLs, for example when
fetching works over HTTP but pushing requires SSH.
+In that case, write both URLs into the `<developerConnection>` element, with
the fetch URL prefixed by `[fetch=]` and the push URL prefixed by `[push=]`:
+
+```xml
+<developerConnection>scm:git:[fetch=]http://mywebserver.org/path_to_repository[push=]ssh://username@otherserver:8898/~/repopath.git</developerConnection>
+```
+
+Further Git provider behavior and its configuration are described on the
[Maven SCM Git page](/scm/git.html).
+
+## Subversion
+
+The `svn` provider accepts the following URLs:
+
+```
+scm:svn:svn://[username[:password]@]server_name[:port]/path_to_repository
+scm:svn:svn+ssh://[username@]server_name[:port]/path_to_repository
+scm:svn:file://[hostname]/path_to_repository
+scm:svn:http://[username[:password]@]server_name[:port]/path_to_repository
+scm:svn:https://[username[:password]@]server_name[:port]/path_to_repository
+```
+
+For example:
+
+```
+scm:svn:file:///svn/root/module
+scm:svn:file://localhost/path_to_repository
+scm:svn:file://my_server/path_to_repository
+scm:svn:http://svn.apache.org/svn/root/module
+scm:svn:https://[email protected]/svn/root/module
+scm:svn:https://username:[email protected]/svn/root/module
+```
+
+The provider configuration is described on the [Maven SCM Subversion
page](/scm/subversion.html).
+
+## Mercurial
+
+The `hg` provider takes the path or URL of the branch location. The supported
protocols are HTTP, HTTPS and FILE, as well as a local path.
+
+```
+scm:hg:url_to_repository/local_repository_directory
+```
+
+For example:
+
+```
+scm:hg:http://host/v3
+scm:hg:file://C:/dev/project/v3 (windows drive)
+scm:hg:file:///home/smorgrav/dev/project/v3 (linux drive)
+scm:hg:/home/smorgrav/dev/project/v3 (local directory)
+```
+
+## Local file system
+
+The `local` provider reads from a directory and has no server. Its URL has
this form:
+
+```
+scm:local<delimiter>path_to_repository<delimiter>module_name
+```
+
+* `path_to_repository`: the absolute or relative path to the parent directory
of your `pom.xml`.
+* `module_name`: the name of the directory that contains your `pom.xml`.
+
+For example:
+
+```
+scm:local:/usr/modules:my_module
+scm:local|C:/javaprojects|my_module
+```
diff --git a/content/markdown/pom.md b/content/markdown/pom.md
index 0eca90ac..b04da4b6 100644
--- a/content/markdown/pom.md
+++ b/content/markdown/pom.md
@@ -1649,21 +1649,21 @@ version control) is an integral part of any healthy
project. If your Maven proje
through Maven. Where connection requires read access for Maven to be able to
find the source
code (for example, an update), developerConnection requires a connection
that will give write
access. The Maven project has spawned another project named
- Maven SCM, which creates a common API for any SCMs that wish to implement
it. The most popular
- are CVS and Subversion, however, there is a growing list of other supported
- [SCMs](/scm/scms-overview.html). All SCM connections are made
- through a common URL structure.
+ Maven SCM, which creates a common API for any SCMs that wish to implement it.
+ All SCM connections are made through a common URL structure.
```
scm:[provider]:[provider_specific]
```
-Where provider is the type of SCM system. For example, connecting to a CVS
repository may look like this:
+Where provider is the type of SCM system. For example, connecting to a Git
repository may look like this:
```
-scm:cvs:pserver:127.0.0.1:/cvs/root:my-project
+scm:git:https://github.com/example/my-project.git
```
+The [SCM URLs](./pom-scm-urls.html) page describes the URL format and the URLs
of the supported SCMs.
+
* `<tag>`:
Specifies the tag that this project lives under. HEAD (meaning, the SCM
root) is the default.
diff --git a/content/site.xml b/content/site.xml
index f2734d96..faa19790 100644
--- a/content/site.xml
+++ b/content/site.xml
@@ -135,7 +135,9 @@ under the License.
<item name="Plugin Prefix Resolution"
href="/guides/introduction/introduction-to-plugin-prefix-mapping.html"/>
<item name="Configuring Default Mojo Executions"
href="/guides/mini/guide-default-execution-ids.html"/>
</item>
- <item name="POM 4.0.0 Reference" href="/pom.html"/>
+ <item name="POM 4.0.0 Reference" href="/pom.html" collapse="true">
+ <item name="SCM URLs" href="/pom-scm-urls.html"/>
+ </item>
<item name="Settings Reference"
href="/settings.html"/> <!-- TODO: all references should be
collected under another area instead/as well, reconsider -->
</item>