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:
- The newer build is looked for. A snapshot is resolved against the metadata of the repository, and the newest build of that snapshot name wins. A release is resolved once and never re-checked.
- A remote repository keeps the builds. The storage name carries a timestamp and a build number, and the metadata points at the newest. The local copy keeps the short name, as the tree above shows.
- -U forces the check. It is the switch for a CI job that must see a teammate’s snapshot at once. In this image it changes nothing, because offline mode has no repository to ask; a local build always uses what is installed.
- A release must never move. Publishing a different 1.0.0 is a broken repository; a -SNAPSHOT of 1.0.0 is the normal working state, and the release drops the suffix when the branch is done.
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