SNAPSHOT versions

A version that ends in -SNAPSHOT is a promise that the artifact may change under the same name. Maven treats it differently from a release in two places: it looks for it again when a build asks, and a repository that serves it keeps the timestamped builds beside the name. For a team it is the version of the branch in progress, and this article shows what a client of a snapshot sees when the library is rebuilt.

The library

The library of the previous article, with the version of a branch rather than a release:

greet/pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>greet</artifactId> <version>1.0.0-SNAPSHOT</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> </project>

greet/src/main/java/com/example/greet/Greeting.java

package com.example.greet; public class Greeting { public String forName(String name) { return "Hello, " + name + "!"; } }

Installed as a snapshot

cd greet
mvn -B install > install.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" install.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:greet >--------------------------
[INFO] Building greet 1.0.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- install:3.1.4:install (default-install) @ greet ---
[INFO] Installing <project>/pom.xml to <HOME>/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/greet-1.0.0-SNAPSHOT.pom
[INFO] Installing <project>/target/greet-1.0.0-SNAPSHOT.jar to <HOME>/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/greet-1.0.0-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

find ~/.m2/repository/com/example/greet -type f | sort | sed "s#$HOME#~#g"

~/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/_remote.repositories
~/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/greet-1.0.0-SNAPSHOT.jar
~/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/greet-1.0.0-SNAPSHOT.pom
~/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/maven-metadata-local.xml
~/.m2/repository/com/example/greet/maven-metadata-local.xml

Five files, one more than a release: inside the version folder there is maven-metadata-local.xml of the snapshot itself, next to the one of the artifact. That file records the build number and the timestamp of the last local install of the snapshot, and it is how the resolver knows whether what it has is the newest build of 1.0.0-SNAPSHOT or an older one.

The file name does not carry a timestamp, because this is the copy in a local repository. A remote repository stores a snapshot as greet-1.0.0-20261122.092000-1.jar and keeps the metadata that maps 1.0.0-SNAPSHOT to the newest of those. A local install simply overwrites the jar, which is why a build that runs after an install sees the new code.

The client

client/pom.xml

<?xml version="1.0" encoding="UTF-8"?> <project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd"> <modelVersion>4.0.0</modelVersion> <groupId>com.example</groupId> <artifactId>client</artifactId> <version>1.0.0</version> <properties> <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding> <maven.compiler.release>21</maven.compiler.release> </properties> <dependencies> <dependency> <groupId>com.example</groupId> <artifactId>greet</artifactId> <version>1.0.0-SNAPSHOT</version> </dependency> </dependencies> </project>

client/src/main/java/com/example/client/Client.java

package com.example.client; import com.example.greet.Greeting; public class Client { public static void main(String[] args) { System.out.println(new Greeting().forName("Maven")); } }

cd ../client
mvn -B package > build.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:client >-------------------------
[INFO] Building client 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ client ---
[INFO] Building jar: <project>/target/client-1.0.0.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

mvn -B -q dependency:build-classpath -Dmdep.outputFile=cp.txt; echo "status: $?"; java -cp target/classes:$(cat cp.txt) com.example.client.Client

status: 0
Hello, Maven!

A new build of the library

The greeting changes and the snapshot is installed again, without touching its version:

greet/src/main/java/com/example/greet/Greeting.java

package com.example.greet; public class Greeting { public String forName(String name) { return "Hi, " + name + "!"; } }

cd ../greet
mvn -B install > install2.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" install2.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:greet >--------------------------
[INFO] Building greet 1.0.0-SNAPSHOT
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] --- install:3.1.4:install (default-install) @ greet ---
[INFO] Installing <project>/pom.xml to <HOME>/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/greet-1.0.0-SNAPSHOT.pom
[INFO] Installing <project>/target/greet-1.0.0-SNAPSHOT.jar to <HOME>/.m2/repository/com/example/greet/1.0.0-SNAPSHOT/greet-1.0.0-SNAPSHOT.jar
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

The client is rebuilt from its own folder with no change at all, and its compile has nothing to do, because the sources are the same and the API did not change:

cd ../client
mvn -B package > build2.log 2>&1; echo "status: $?"; sed "s#$PWD#<project>#g" build2.log

status: 0
[INFO] Scanning for projects...
[INFO]
[INFO] -------------------------< com.example:client >-------------------------
[INFO] Building client 1.0.0
[INFO] from pom.xml
[INFO] --------------------------------[ jar ]---------------------------------
[INFO]
[INFO] No tests to run.
[INFO]
[INFO] --- jar:3.5.0:jar (default-jar) @ client ---
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: <TIME>
[INFO] Finished at: <TIMESTAMP>
[INFO] ------------------------------------------------------------------------

java -cp target/classes:$(cat cp.txt) com.example.client.Client

Hi, Maven!

The program prints the new greeting, although nothing in the client was recompiled: the class path points at the jar in the local repository, and that jar is the one the second install wrote. That is the behaviour a snapshot promises and a release refuses: a released 1.0.0 that changes under a client would make two builds of the same source produce two programs.

What the suffix means

Maven reads -SNAPSHOT as a literal suffix of the version string and changes its resolution behaviour for it:

A project that depends on a snapshot is not reproducible in the way a release is: two builds a day apart can produce different jars from the same source. That is why a release build refuses to depend on one by default in some setups, and why the version of every library a project ships is a release, not a snapshot.

Where to go next

Profiles and their activation closes the part of the course about the pom and the two ways a build can be told which configuration to use.

Article author: Arthur Isaev