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

Reply via email to