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-archetype.git
The following commit(s) were added to refs/heads/master by this push:
new 9d4b0489 Document the real archetypeCatalog default and catalogs
9d4b0489 is described below
commit 9d4b04891673dd23b426babc54557c772f336987
Author: Sylwester Lachiewicz <[email protected]>
AuthorDate: Sat Oct 31 17:04:38 2026 +0000
Document the real archetypeCatalog default and catalogs
---
.../examples/generate-alternative-catalog.md | 66 +++-------------------
.../markdown/specification/archetype-catalog.md | 14 ++---
.../src/site/markdown/specification/generate.md | 6 +-
3 files changed, 17 insertions(+), 69 deletions(-)
diff --git
a/maven-archetype-plugin/src/site/markdown/examples/generate-alternative-catalog.md
b/maven-archetype-plugin/src/site/markdown/examples/generate-alternative-catalog.md
index f1cd53d8..b49cc32f 100644
---
a/maven-archetype-plugin/src/site/markdown/examples/generate-alternative-catalog.md
+++
b/maven-archetype-plugin/src/site/markdown/examples/generate-alternative-catalog.md
@@ -26,66 +26,16 @@ under the License.
# Generate project using an alternative catalog
-It is possible to use an alternative catalog as the internal one by defining
the `archetypeCatalog` property to a specific value which can be one of:
+You can choose the catalogs that `archetype:generate` lists by setting the
`archetypeCatalog` property to a comma-separated list of the following values:
-- `internal` to use the internal catalog only.
-- `local` to use the local catalog only.
-- `remote` to use the maven's remote catalog. No catalog is currently provided.
+- `remote` to use the `archetype-catalog.xml` that Maven Central publishes, or
the one from a repository with the id `archetype`. If the remote catalog is
empty or cannot be retrieved, the plugin uses the internal catalog instead.
+- `local` to use the `archetype-catalog.xml` in your local repository, which
`archetype:create-from-project` updates.
+- `internal` to use the catalog bundled with the plugin.
-The default value is `remote,local`. Thus the local catalog is shown just
after the remote one.
+The default value is `remote,local`, so the local catalog is listed just after
the remote one. Other values are rejected.
+
+To list only the archetypes of your local repository, run the following
command:
```shell
-$ mvn archetype:generate
-[INFO] Scanning for projects...
-[INFO] Searching repository for plugin with prefix: 'archetype'.
-[INFO] ------------------------------------------------------------------------
-[INFO] Building Maven Default Project
-[INFO] task-segment: [archetype:generate] (aggregator-style)
-[INFO] ------------------------------------------------------------------------
-[INFO] Preparing archetype:generate
-[INFO] No goals needed for project - skipping
-[INFO] Setting property: classpath.resource.loader.class =>
'org.codehaus.plexus.velocity.ContextClassLoaderResourceLoader'.
-[INFO] Setting property: velocimacro.messages.on => 'false'.
-[INFO] Setting property: resource.loader => 'classpath'.
-[INFO] Setting property: resource.manager.logwhenfound => 'false'.
-[INFO] [archetype:generate]
-[INFO] Generating project in Interactive mode
-[INFO] No archetype defined. Using maven-archetype-quickstart
(org.apache.maven.archetypes:maven-archetype-quickstart:1.0)
-Choose archetype:
-1: http://cocoon.apache.org -> cocoon-22-archetype-block-plain (Creates an
empty Cocoon block; useful if you want to add another block to a Cocoon
application)
-2: http://cocoon.apache.org -> cocoon-22-archetype-block (Creates a Cocoon
block containing some small samples)
-3: http://cocoon.apache.org -> cocoon-22-archetype-webapp (Creates a web
application configured to host Cocoon blocks. Just add the block dependencies)
-Choose a number or apply filter (format: [groupId:]artifactId, case sensitive
contains): 1
-Downloading:
http://localhost:8081/nexus/content/groups/mac/org/apache/cocoon/cocoon-22-archetype-block-plain/1.0.0/cocoon-22-archetype-block-plain-1.0.0.jar
-13K downloaded
-Define value for groupId: : com.company
-Define value for artifactId: : example
-Define value for version: 1.0-SNAPSHOT: :
-Define value for package: com.company: : com.company.example
-Confirm properties configuration:
-groupId: com.company
-artifactId: example
-version: 1.0-SNAPSHOT
-package: com.company.example
- Y: :
-[INFO]
----------------------------------------------------------------------------
-[INFO] Using following parameters for creating OldArchetype:
cocoon-22-archetype-block-plain:1.0.0
-[INFO]
----------------------------------------------------------------------------
-[INFO] Parameter: groupId, Value: com.company
-[INFO] Parameter: packageName, Value: com.company.example
-[INFO] Parameter: package, Value: com.company.example
-[INFO] Parameter: artifactId, Value: example
-[INFO] Parameter: basedir, Value: /private/tmp/archetype
-[INFO] Parameter: version, Value: 1.0-SNAPSHOT
-[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference
: template = archetype-resources/pom.xml [line 20,column 6] : $Id is not a
valid reference.
-[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference
: template =
archetype-resources/src/main/resources/META-INF/cocoon/spring/block-servlet-service.xml
[line 20,column 6] : $Id is not a valid reference.
-[WARNING] org.apache.velocity.runtime.exception.ReferenceException: reference
: template =
archetype-resources/src/main/resources/META-INF/cocoon/spring/block-application-context.xml
[line 18,column 6] : $Id is not a valid reference.
-[INFO] OldArchetype created in dir: /private/tmp/archetype/example
-[INFO] ------------------------------------------------------------------------
-[INFO] BUILD SUCCESSFUL
-[INFO] ------------------------------------------------------------------------
-[INFO] Total time: 1 minute 20 seconds
-[INFO] Finished at: Tue Sep 09 19:10:51 CEST 2008
-[INFO] Final Memory: 8M/15M
-[INFO] ------------------------------------------------------------------------
+mvn archetype:generate -DarchetypeCatalog=local
```
diff --git
a/maven-archetype-plugin/src/site/markdown/specification/archetype-catalog.md
b/maven-archetype-plugin/src/site/markdown/specification/archetype-catalog.md
index 2bcd20bd..76e5a925 100644
---
a/maven-archetype-plugin/src/site/markdown/specification/archetype-catalog.md
+++
b/maven-archetype-plugin/src/site/markdown/specification/archetype-catalog.md
@@ -30,9 +30,7 @@ Knowledge about archetypes is stored in catalogs.
The catalogs are xml files: see the [reference
documentation](../../archetype-models/archetype-catalog/archetype-catalog.html).
-The Archetype Plugin comes bundled with an internal catalog. This one is used
by default.
-
-The Archetype Plugin can use catalogs from local filesystem and from HTTP
connections.
+The Archetype Plugin comes bundled with an [internal
catalog](../../archetype-common/internal.html). By default,
`archetype:generate` lists the `remote` catalog, which is the
`archetype-catalog.xml` that Maven Central publishes, followed by the `local`
catalog. It falls back to the internal catalog when the remote one is empty or
cannot be retrieved.
## Catalog file explained
@@ -82,10 +80,10 @@ The `crawl-repository` goal is used to create a catalog
file by crawling a Maven
## Location of catalog files
-The Archetype Plugin knows by default about its internal catalog. It also
knows about the `local` and `remote` catalogs.
-
-`local` represents the `~/.m2/archetype-catalog.xml` catalog file.
+The Archetype Plugin knows three catalogs, selected with the
`archetypeCatalog` property of `archetype:generate` (default `remote,local`):
-`remote` represents the
`https://repo.maven.apache.org/maven2/archetype-catalog.xml` catalog file.
+- `internal` is the catalog bundled with the plugin.
+- `local` represents the `archetype-catalog.xml` file in the root of the local
repository (by default `~/.m2/repository/archetype-catalog.xml`).
+- `remote` represents the `archetype-catalog.xml` file of the repository with
the id `archetype`, of Maven Central
(`https://repo.maven.apache.org/maven2/archetype-catalog.xml`), or of the
mirror of either.
-The Archetype Plugin can also read catalogs from filesystem/HTTP by providing
the path/URL of a catalog file or of a directory containing an
`archetype-catalog.xml` file.
+To read the catalog from a different repository, declare it with the id
`archetype` in your `settings.xml` and use the `remote` catalog. Other values
of `archetypeCatalog`, such as a file path or a URL, are not supported.
diff --git a/maven-archetype-plugin/src/site/markdown/specification/generate.md
b/maven-archetype-plugin/src/site/markdown/specification/generate.md
index c3d26829..e5234ecf 100644
--- a/maven-archetype-plugin/src/site/markdown/specification/generate.md
+++ b/maven-archetype-plugin/src/site/markdown/specification/generate.md
@@ -52,10 +52,10 @@ If the Archetype Plugin is configured to create a project
in an existing directo
It is possible to call the Archetype Plugin to generate a project in batch
mode (to get rid of the prompting). This is achieved by providing the Archetype
Plugin with all the needed values as system properties.
-- `archetypeCatalog` which specifies the catalog(s). The valid catalogs are:
`internal` (the default), `local`, `remote`.
- - `internal` uses an internal catalog
+- `archetypeCatalog` which specifies the catalog(s) as a comma-separated list.
The default is `remote,local`. The valid catalogs are `remote`, `local` and
`internal`.
+ - `remote` uses the `archetype-catalog.xml` from Maven Central, or from
the repository with the id `archetype`, either direct or through a mirror. If
that catalog is empty or cannot be retrieved, the internal catalog is used
instead.
- `local` uses the `archetype-catalog.xml` file from the local repository
- - `remote` uses the `archetype-catalog.xml` from Maven Central, either
direct or via a repository manager file
+ - `internal` uses the catalog bundled with the plugin
- `archetypeGroupId` specifies the groupId of the archetype to use
- `archetypeArtifactId` specifies the artifactId of the archetype to use
- `archetypeVersion` specifies the version of the archetype to use