blob: 9b29c5da1b36447f96b1e73248b0e4614ca2e176 [file] [log] [blame]
Benson Margulies
~~ 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
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ KIND, either express or implied. See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~ NOTE: For help with the syntax of this file, see:
The maven-scm-publish-plugin is a utility plugin to allow publishing Maven
website to any supported SCM.
The primary goal was to have an utility plugin to allow Apache projects
to publish Maven websites via the {{{}ASF svnpubsub system}}.
In addition to SCM operations, it takes care to fix newline inconsistencies
generated by <<<maven-site-plugin>>> (see {{{}MSITE-121}}),
which prevents simple content import to SCM.
The plugin has been tested with Git SCM too and by example can
{{{./various-tips.html#Git_branch}push content for GitHub Pages}}.
* Implementation
The plugin works from <<staged website>> by default (see {{{./publish-scm-mojo.html#content}<<<content>>> parameter}}).
It first checks out the contents of a directory from
the SCM (see {{{./publish-scm-mojo.html#pubScmUrl}<<<pubSubUrl>>> parameter}}) into
<<<target/scmpublish-checkout>>> by default (see {{{./publish-scm-mojo.html#checkoutDirectory}<<<checkoutDirectory>>> parameter}}).
Then locally staged content is applied to the check-out, issuing
appropriate SCM commands to add and delete entries, followed by a
The <<scmpublish.dryRun>> parameter to the plugin avoids all
SCM operations, and simply logs out the added, deleted,
and changed files.
The <<scmpublish.skipCheckin>> parameter omits the final checkin.
This allows you to visit <<<target/scmpublish-checkout>>>, and validate
its contents before submitting to the SCM.
* Publishing any content to SCM
Even without any <<<pom.xml>>>/Maven project, you can update SCM content with
a local content:
mvn scm-publish:publish-scm -Dscmpublish.pubScmUrl=scm:<scm-provider>... -Dscmpublish.content=...path-to-content...
SCM content will be checked-out to a temporary directory, then local content will
be applied to the check-out, before it is checked-in back.
See {{{./examples/importing-maven-site.html} content import script}} for an
<<See {{{./various-tips.html}Some Tips}}.>>
* Known Limitations
There are 2 known limitations:
* for Subversion, the plugin can create the initial SCM directory if it does not exist. But for Git by example, if you use a branch,
the branch won't be created: you have to {{{./various-tips.html#Git_branch}create it manually}},
* the plugin works well for multi-module websites publishing to a complete directory:
you just need to publish <<<mvn site:stage>>> content. But if one module does not publish
its content to the same directory (like Surefire or Enforcer, which have a
base directory and one plugin in <<</plugins/>>>), this staging area can't be simply imported.
* Future Dreams
Ideally, scm urls would be supported in <<<\<distributionManagement>>>> section of the POM, then
publishing would simply be <<<mvn site-deploy>>>, without any problems for non-flat multi-modules
To reach such a dream, there are some steps:
* fix inconsistent newlines generated by <<<maven-site-plugin>>> (caused by <<<site.vm>>> template and
resources taken from skin jar without fixing newlines): {{{}MSITE-121}}
is fixed in maven-site-plugin 3.4,
* improve {{{/wagon/wagon-providers/wagon-scm/}<<<wagon-scm>>>}} to put a whole directory content
in one commit, and not with one commit per file.
Then this plugin would be outdated, replaced by natural <<<maven-site-plugin:deploy>>> goal.