Usage

The Maven Wagon Plugin, as the name implies, allows you to use various functions of a Maven wagon. It allows you to upload resources from your build to a remote location using wagon. It allows you to download resources from a repository using wagon. It allows to list the content of a repository using wagon. Finally, by combining the upload and download capabilities, it can merge a Maven repository to another in a generic way.

The configuration are similar to FileSet in maven-assembly-plugin, maven-scm-plugin, etc.

However, due to some differences in term of provider implementation, not all goals are working as expected. In general, a good way to see a particular wagon implementation would work with this plugin is to run wagon:list goal against its URL.

The following contains a list of known limitations:

This plugin brings its own wagon providers for file:, http(s):, scp: and sftp: URLs (wagon-file, wagon-http and wagon-ssh), so it does not depend on the providers a Maven distribution ships. Other protocols, such as dav: or ftp:, still need the provider as a build extension.
The bundled wagon-http cannot list remote directories, so list and a download that has to scan the remote directory do not work over http(s): with it. Since wagon-http 3.5.0 an HTTP server is no longer treated as a directory tree, because HTTP has no directory semantics ( WAGON-618). For these goals, prefer a protocol that can list: dav:http(s):// with the wagon-webdav-jackrabbit provider when the server speaks WebDAV, or sftp:, scp:, ftp: or file:. Only as a last resort, declare a wagon-http up to 3.4.3 (for example 3.3.4) as a dependency of the plugin; it replaces the bundled one and still parses HTML directory listings. A wagon-http build extension is not used for these URLs, because the plugin's own provider takes precedence.
Since ftp wagon provider is not part of your maven distribution, you will need to copy
- wagon-ftp-beta-6.jar
- oro-2.0.8.jar
- commons-net-1.4.1.jar
to your $MAVEN_HOME/lib directory.
list and download work over dav:http(s):// with the wagon-webdav-jackrabbit provider (org.apache.maven.wagon:wagon-webdav-jackrabbit), declared as a build extension or as a dependency of the plugin. They did not work with the older Slide based wagon-webdav provider.
list and download goals are very slow since it needs to scan the remote file system. So use includes and excludes wisely to limit the search. For example: includes=**/somefile scans the entire remote source tree.
This plugin does not work with Maven 3.0.x and 3.1.x out of the box due to missing the following libraries in it distribution: commons-io-2.x, common-lang-2.x, and jsoup-1.x. You can invoke wagon:update-maven-3 to add the missing files to $MAVEN_HOME/lib. See WAGON-407 for details

The following contains a couple of usage examples. Live examples are available in Git

Configuration example to upload

<project>
  [...]
  <build>
    [...]
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-ssh</artifactId>
        <version>3.5.3</version>
      </extension>
    </extensions>

    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>wagon-maven-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
          <execution>
            <id>upload-javadoc</id>
            <phase>deploy</phase>
            <goals>
              <goal>upload</goal>
            </goals>
            <configuration>
              <fromDir>local.dir</fromDir>
              <includes>*</includes>
              <excludes>pom.xml</excludes>
              <url>scp://your.remote.host/</url>
              <toDir>remote.dir</toDir>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

Configuration example to download

<project>
  [...]
  <build>
    <extensions>
      <extension>
        <groupId>org.apache.maven.wagon</groupId>
        <artifactId>wagon-webdav-jackrabbit</artifactId>
        <version>3.5.3</version>
      </extension>
    </extensions>

    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>wagon-maven-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
          <execution>
            <id>download-test-data</id>
            <phase>pre-integration-test</phase>
            <goals>
              <goal>download</goal>
            </goals>
            <configuration>
              <serverId>atlassian-public</serverId>
              <url>dav:https://maven.atlassian.com/public</url>
              <fromDir>com/atlassian/jira/plugins/jira-plugin-test-resources/${pom.version}</fromDir>
              <toDir>target/test-data</toDir>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>

Configuration example to merge Maven repositories

  mvn org.codehaus.mojo:wagon-maven-plugin:3.2.0:merge-maven-repos \
     -Dwagon.source=http://people.apache.org/~olamy/staging-repo \
     -Dwagon.target=scp://localhost/$LOGNAME/maven-repo

Configuration example to copy files under one URL to another URL

  mvn org.codehaus.mojo:wagon-maven-plugin:3.2.0:copy \
     -Dwagon.source=http://people.apache.org/~olamy/staging-repo \
     -Dwagon.target=scp://localhost/home/$LOGNAME/maven-repo

Configuration example to execute commands

The sshexec goal runs commands over the scp: or sftp: provider this plugin brings, so it needs no build extension.

<project>
  [...]
  <build>
    <plugins>
      <plugin>
        <groupId>org.codehaus.mojo</groupId>
        <artifactId>wagon-maven-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
          <execution>
            <id>execute-test-commands</id>
            <phase>deploy</phase>
            <goals>
              <goal>sshexec</goal>
            </goals>
            <configuration>
              <serverId>atlassian-public</serverId>
              <url>scp://maven.atlassian.com/public</url>
              <commands>
                <command>/usr/share/tomcat/bin/tomcat stop</command>
                <command>rm -rf /usr/share/tomcat/webapps/ROOT</command>
                <command>unzip -o /usr/share/tomcat/webapps/myapp.zip -d /usr/share/tomcat/webapps/</command>
                <command>/usr/share/tomcat/bin/tomcat start</command>
              </commands>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
  [...]
</project>