Various tips for using this plugin

URL format

You must use a scm url format:

  scm:<scm_provider><delimiter><provider_specific_part>

Example for svn: scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/

And configure is as it:

  <distributionManagement>
    <site>
      <id>site_id</id>
      <url>scm:svn:https://svn.apache.org/repos/infra/websites/production/maven/content/plugins/maven-scm-publish-plugin/</url>
    </site>
  </distributionManagement>

NOTE: with svn, if the remote url doesn't exist, it will be created.

Git branch

To use Git branch (for example: GitHub gh-pages)

  <distributionManagement>
    <site>
      <id>site_id</id>
      <url>scm:git:https://gitbox.apache.org/repos/asf/maven-scm-publish-plugin.git</url><!-- or scm:git:ssh://git@github.com/username/tomcat-foo-artifact.git -->
    </site>
  </distributionManagement>
...
    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-scm-publish-plugin</artifactId>
      <version>3.2.1</version>
      <configuration>
        <scmBranch>gh-pages</scmBranch>
      </configuration>
    </plugin>

Initial creation of the branch has to be done manually, as a Git orphan branch:

1. git checkout --orphan gh-pages to create the branch locally,

2. rm .git/index ; git clean -fdx to clean the branch content and let it empy,

3. copy an initial site content,

4. commit and push: git add *, git commit -m "initial site content", git push

Improving SCM Checkout Performance

By default, a complete checkout is done. You can configure the plugin to try update rather than a full checkout/clone

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-scm-publish-plugin</artifactId>
      <version>3.2.1</version>
      <configuration>
        <tryUpdate>true</tryUpdate>
      </configuration>
    </plugin>

By default, the scm content is checked-out/cloned to ${project.build.directory}/scmpublish-checkout, so when running mvn clean, all the content is deleted. You can configure a path to your machine to avoid full checkout. A recommended way is to use a property with a default value that your colleague will be able to override in their settings.

    <properties>
      ...
      <!-- override in your settings -->
      <siteMainDirectory>${user.home}</siteMainDirectory>
      <scmPubCheckoutDirectory>\${siteMainDirectory}/my-site-content-scm</scmPubCheckoutDirectory>
      ...
    </properties>

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-scm-publish-plugin</artifactId>
      <version>3.2.1</version>
      <configuration>
        <checkoutDirectory>${scmPubCheckoutDirectory}</checkoutDirectory>
        <tryUpdate>true</tryUpdate>
      </configuration>
    </plugin>

Using alternate scm provider

You can use svnjava rather than default svn cli if you use a machine without svn cli.

    <plugin>
      <groupId>org.apache.maven.plugins</groupId>
      <artifactId>maven-scm-publish-plugin</artifactId>
      <version>3.2.1</version>
      <configuration>
        <providerImplementations>
          <svn>javasvn</svn>
        </providerImplementations>
      </configuration>
      <dependencies>
        <dependency>
          <groupId>com.google.code.maven-scm-provider-svnjava</groupId>
          <artifactId>maven-scm-provider-svnjava</artifactId>
          <version>2.0.6</version>
        </dependency>
        <dependency>
          <groupId>org.tmatesoft.svnkit</groupId>
          <artifactId>svnkit</artifactId>
          <version>1.7.11</version>
        </dependency>
      </dependencies>
    </plugin>