Install rule: add CONF_INSTALL_VERSION_ALIAS (version-named symlinks); harmonize CONF_INSTALL_SYMLINK cleanup.

Amaury · Amaury · commit 0a6a755cfafa · 2026-06-11T13:03:17.000+02:00
- New CONF_INSTALL_VERSION_ALIAS configuration: each listed file or directory
  is aliased by a symlink which name contains the installed version number
  ('style.css' pointed by 'style-1.2.0.css') or the main branch's name.
- CONF_INSTALL_SYMLINK: links cleanup is now pattern-based (version numbers
  and main branch name, non-committed links only), the 'main'-named link is
  created when the main branch is deployed, and links are never created over
  committed files.
- Documentation and example configuration updated.
diff --git a/README.md b/README.md
@@ -169,10 +169,11 @@ $ dpk install --platform=test --tag=3.2.1
 Dispak will perform these operations:
 - On production server, check if the requested tag is not an unstable version (see [above](#112-version-numbering)).
 - Fetch and read the configuration file from the tag.
-- Remove previously created symlink (see [below](#35-static-files-symlinks-and-amazon-s3)).
+- Remove version-named symlinks and version alias links created by previous deployments (see [below](#35-static-files-symlinks-and-amazon-s3)).
 - Execute pre-install scripts (see [below](#33-prepost-scripts-execution)).
 - Execute pre-configuration scripts (see [below](#33-prepost-scripts-execution)).
 - **Deploy new version's source code.**
+- Create version-named symlinks and version alias links (see [below](#35-static-files-symlinks-and-amazon-s3)).
 - Install crontab file (see [below](#32-crontab-installation)).
 - Perform database migration (see [below](#31-database-migrations)).
 - Install Apache configuration files (see [below](#37-apache-configuration)).
@@ -509,28 +510,61 @@ Generator scripts are listed in the `CONF_INSTALL_GENERATE` variable of the [con
 
 Dispak helps you to manage the static files of your web projects.
 
-There is two (non-mutually exclusive) ways to manage these files: Using symlink, and copying files to Amazon S3.
+There is three (non-mutually exclusive) ways to manage these files: Using symlinks, using version alias links, and copying files to Amazon S3.
 
 #### Symbolic links
-You can define a list of symbolic links in the [configuration file](#311-configuration-file). These links will be created during the tag installation process. In fact, you define the target of each link (usually a directory but it can be a file), and the directory where these links are going to be created. The created links are named with the installed version's number.
+You can define a list of symbolic links in the [configuration file](#311-configuration-file). These links will be created during the installation process. In fact, you define the target of each link (usually a directory but it can be a file), and the directory where these links are going to be created. The created links are named with the installed version's number, or with the name of the main branch when the main branch is deployed. The target is interpreted relative to the link's directory.
 
 Example: Let's say your configuration file contains this line:
 ```shell
-CONF_INSTALL_SYMLINK["www/css"]="www/css"
+CONF_INSTALL_SYMLINK["www/css"]="."
 ```
 
 Now, when the version `1.2.0` is installed, the following link will be created:
 ```shell
 $ ls -l www/css/1.2.0
 www/css/1.2.0 -> .
 ```
+And when the `main` branch is deployed (on a test server for example), the `www/css/main` link is created the same way.
+
+Before each deployment, the symbolic links created by previous deployments are removed: every *symbolic link* of the configured directories whose name is a version number (`X.Y.Z`) or the main branch's name is deleted — unless it is committed in the git repository. Committed links are never removed, and no new link is created if its name is already used by a committed link or file.
 
 Then you can adapt your templates:
 ```html
 <link href="/css/{$conf.version}/style.css" rel="stylesheet">
 ```
 (in this example, the `$conf.version` variable have been defined in the framework's configuration file, thanks to the [file generation](#34-files-generation) feature)
 
+#### Version alias links
+While the symbolic links described above put the version number in the *path* of the URL (a whole directory at once), Dispak can also put the version number in the *name* of selected files or directories, by creating version-named symbolic links next to them. It is the usual way to do [cache busting](https://www.keycdn.com/support/what-is-cache-busting) with named assets (`bundle-1.2.0.js`).
+
+List the files and/or directories in the `CONF_INSTALL_VERSION_ALIAS` variable of the [configuration file](#311-configuration-file):
+```shell
+CONF_INSTALL_VERSION_ALIAS="
+	www/css/style.css
+	www/js
+"
+```
+
+When the version `1.2.0` is installed, the following links are created:
+```shell
+$ ls -l www/css/style-1.2.0.css www/js-1.2.0
+www/css/style-1.2.0.css -> style.css
+www/js-1.2.0 -> js
+```
+And when the `main` branch is deployed, the `www/css/style-main.css` and `www/js-main` links are created the same way.
+
+The name of the link is computed from the name of the aliased element:
+- For a file with an extension, the version is added before the last extension (`style.css` → `style-1.2.0.css`, `jquery.min.js` → `jquery.min-1.2.0.js`).
+- For a file without extension, a dot file or a directory (even if its name contains a dot), the version is added at the end of the name (`toto` → `toto-1.2.0`, `assets.css/` → `assets.css-1.2.0`).
+
+Then you can adapt your templates:
+```html
+<link href="/css/style-{$conf.version}.css" rel="stylesheet">
+```
+
+The cleanup rules are the same as for the symbolic links above: before each deployment, the version alias links of previous deployments are removed if they are not committed; committed links are never removed, and no new link is created if its name is already used by a committed link or file. If a listed element is removed from the configuration, its old alias links must be removed manually.
+
 #### Amazon S3
 It is also possible to define a bucket on Amazon S3 where your static files will be copied each time you create a *stable* version (or even for *unstable* version if you defined the `CONF_PKG_S3_UNSTABLE` configuration variable). A subdirectory will be created, named as the tag version number, and all configured files will be copied there.
 
@@ -640,7 +674,8 @@ Here are the definable variables:
   - `CONF_PKG_S3_COMPRESS`: Set this variable to 1 if you want to compress text files (raw text, HTML, JSON, SVG…) sent to Amazon S3. Files are compressed with GZIP. Note that files are compressed and sent one by one, whereas folder synchronization is used when there is no compression. As a result, upload is quite slower with compression.
   - `CONF_PKG_S3_UNSTABLE`: Set this variable to 1 if you want to copy static files to Amazon S3 for stable *and* unstable versions (not only for stable versions).
 - **install rule**
-  - `CONF_INSTALL_SYMLINK`: Use this variable if you need to create symlinks when you install a new version. It is an associative array; the key is the path to the link's directory; the value is the path pointed by the link. The link will be created in its destination directory, and its name is the installed tag's version number.
+  - `CONF_INSTALL_SYMLINK`: Use this variable if you need to create symlinks when you install a new version. It is an associative array; the key is the path to the link's directory; the value is the path pointed by the link (interpreted relative to the link's directory). The link will be created in its destination directory, and its name is the installed tag's version number (or the main branch's name when the main branch is deployed). Links created by previous deployments are removed, unless they are committed.
+  - `CONF_INSTALL_VERSION_ALIAS`: List of files and/or directories that must be aliased by a version-named symlink, created next to them (`www/css/style.css` is pointed by the `www/css/style-1.2.0.css` link when the `1.2.0` tag is installed). Links created by previous deployments are removed, unless they are committed.
   - `CONF_INSTALL_SCRIPTS_PRE`: Here is a list of scripts to execute before install.
   - `CONF_INSTALL_SCRIPTS_POST`: Here is a list of scripts to execute after install. The scripts are not executed if an error has occured during the install process.
   - `CONF_CONFIG_SCRIPTS_PRE`: Here is a list of scripts to execute before install (after pre-install scripts) or at the beginning of configuration (`dpk config` command).
diff --git a/dispak-example.conf b/dispak-example.conf
@@ -55,6 +55,13 @@ CONF_PKG_S3["static.skriv.com"]="static.skriv.com/www"
 # Symlinks to create (key: where to create the link; value: what is pointed by the link)
 CONF_INSTALL_SYMLINK["/path/to/www"]="/path/to/www"
 
+# Files and directories aliased with a version-named symlink
+# (e.g. '/path/to/www/css/style.css' pointed by a '/path/to/www/css/style-1.2.0.css' link)
+CONF_INSTALL_VERSION_ALIAS="
+	/path/to/www/css/style.css
+	/path/to/www/js
+"
+
 # pre-install scripts
 CONF_INSTALL_SCRIPTS_PRE="/path/to/scripts/pre-install"
 
diff --git a/rules/03-install.sh b/rules/03-install.sh
@@ -78,16 +78,14 @@ rule_exec_install() {
 		# reset the configuration file
 		git restore --staged --worktree "$GIT_REPO_PATH/etc/dispak.conf"
 	fi
-	# remove symlinks from the currently installed tag
+	# get the currently deployed branch or tag (used as parameter of pre/post scripts)
 	CURRENT_TAG="$(git symbolic-ref -q --short HEAD || git describe --tags --exact-match)"
-	if [ "$CURRENT_TAG" != "$CONF_GIT_MAIN" ] && [ ${#CONF_INSTALL_SYMLINK[@]} -ne 0 ]; then
-		for _SYMLINK in ${!CONF_INSTALL_SYMLINK[@]}; do
-			if [ -L "$_SYMLINK/$CURRENT_TAG" ]; then
-				echo "$(ansi bold)Removing symlink $(ansi reset)$(ansi dim)$_SYMLINK/$CURRENT_TAG$(ansi reset)"
-				rm -f "$_SYMLINK/$CURRENT_TAG"
-			fi
-		done
-	fi
+	# remove version-named symlinks created by previous deployments
+	for _SYMLINK in ${!CONF_INSTALL_SYMLINK[@]}; do
+		_install_clean_version_links "$_SYMLINK" "" ""
+	done
+	# remove version alias links created by previous deployments
+	_install_version_alias_cleanup
 	# execute pre-install scripts
 	_install_pre_scripts
 	# execute pre-config scripts
@@ -103,12 +101,18 @@ rule_exec_install() {
 		if ! git checkout "tags/${DPK_OPT["tag"]}" --quiet ; then
 			abort "$(ansi red)Failed to update repository to tag '${DPK_OPT["tag"]}'.$(ansi reset)"
 		fi
-		# create symlinks
-		for _SYMLINK in ${!CONF_INSTALL_SYMLINK[@]}; do
-			echo "$(ansi bold)Create symlink $(ansi reset)$(ansi dim)${CONF_INSTALL_SYMLINK["$_SYMLINK"]}/${DPK_OPT["tag"]}$(ansi reset)"
-			ln -s "${CONF_INSTALL_SYMLINK["$_SYMLINK"]}" "$_SYMLINK/${DPK_OPT["tag"]}"
-		done
 	fi
+	# create symlinks (named with the tag number, or the main branch's name)
+	for _SYMLINK in ${!CONF_INSTALL_SYMLINK[@]}; do
+		if [ -e "$_SYMLINK/${DPK_OPT["tag"]}" ] || [ -L "$_SYMLINK/${DPK_OPT["tag"]}" ]; then
+			# a committed link or file already uses this name
+			continue
+		fi
+		echo "$(ansi bold)Create symlink $(ansi reset)$(ansi dim)$_SYMLINK/${DPK_OPT["tag"]}$(ansi reset)"
+		ln -sn "${CONF_INSTALL_SYMLINK["$_SYMLINK"]}" "$_SYMLINK/${DPK_OPT["tag"]}"
+	done
+	# create version alias links
+	_install_version_alias
 	# install crontab
 	_install_crontab
 	# database migration
@@ -173,6 +177,94 @@ _install_post_scripts() {
 	echo "$(ansi gree)Done$(ansi reset)"
 }
 
+# _install_clean_version_links()
+# Remove the symbolic links of a directory which names contain a version number
+# (or the main branch's name) and that are not committed.
+# @param	string	Path to the directory to process.
+# @param	string	Prefix of the links' names (may be empty).
+# @param	string	Suffix of the links' names (may be empty).
+_install_clean_version_links() {
+	for _VLINK in "$1/$2"*"$3"; do
+		# this test must stay the first instruction of the loop: it absorbs the
+		# literal pattern given by bash when the glob matches nothing
+		if [ ! -L "$_VLINK" ]; then
+			continue
+		fi
+		# extract the version part of the link's name
+		_VPART="${_VLINK##*/}"
+		_VPART="${_VPART#"$2"}"
+		_VPART="${_VPART%"$3"}"
+		if ! [[ "$_VPART" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] && [ "$_VPART" != "$CONF_GIT_MAIN" ]; then
+			continue
+		fi
+		# committed links are never removed
+		if git ls-files --error-unmatch -- "$_VLINK" > /dev/null 2>&1; then
+			continue
+		fi
+		echo "$(ansi bold)Removing symlink $(ansi reset)$(ansi dim)$_VLINK$(ansi reset)"
+		rm -f "$_VLINK"
+	done
+}
+
+# _install_version_alias_cleanup()
+# Remove the version alias links created by previous deployments.
+_install_version_alias_cleanup() {
+	if [ "$CONF_INSTALL_VERSION_ALIAS" = "" ]; then
+		return
+	fi
+	for _ALIAS in $CONF_INSTALL_VERSION_ALIAS; do
+		_ALIAS_DIR="$(dirname "$_ALIAS")"
+		_ALIAS_BASE="$(basename "$_ALIAS")"
+		# version added at the end of the name (directories, files without extension)
+		_install_clean_version_links "$_ALIAS_DIR" "${_ALIAS_BASE}-" ""
+		# version added before the file's extension
+		if [[ "${_ALIAS_BASE:1}" == *.* ]]; then
+			_install_clean_version_links "$_ALIAS_DIR" "${_ALIAS_BASE%.*}-" ".${_ALIAS_BASE##*.}"
+		fi
+	done
+}
+
+# _install_version_alias()
+# Create version alias links: for each listed file or directory, a symbolic link
+# which name contains the installed version number (or the main branch's name).
+_install_version_alias() {
+	if [ "$CONF_INSTALL_VERSION_ALIAS" = "" ]; then
+		return
+	fi
+	# the version must be a tag number or the main branch's name
+	if ! [[ "${DPK_OPT["tag"]}" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] && [ "${DPK_OPT["tag"]}" != "$CONF_GIT_MAIN" ]; then
+		warn "Tag '$(ansi dim)${DPK_OPT["tag"]}$(ansi reset)' doesn't match the X.Y.Z format, no version alias created."
+		return
+	fi
+	echo "$(ansi bold)Create version alias links$(ansi reset)"
+	for _ALIAS in $CONF_INSTALL_VERSION_ALIAS; do
+		# check the aliased element exists
+		if [ ! -e "$_ALIAS" ] && [ ! -L "$_ALIAS" ]; then
+			warn "Unable to find '$(ansi dim)$_ALIAS$(ansi reset)', no alias created."
+			continue
+		fi
+		_ALIAS_DIR="$(dirname "$_ALIAS")"
+		_ALIAS_BASE="$(basename "$_ALIAS")"
+		# compute the link's name
+		if [ -d "$_ALIAS" ] || [[ "${_ALIAS_BASE:1}" != *.* ]]; then
+			# directory, file without extension or dot file: version added at the end
+			_ALIAS_LINK="$_ALIAS_DIR/${_ALIAS_BASE}-${DPK_OPT["tag"]}"
+		else
+			# file: version added before the extension
+			_ALIAS_LINK="$_ALIAS_DIR/${_ALIAS_BASE%.*}-${DPK_OPT["tag"]}.${_ALIAS_BASE##*.}"
+		fi
+		# create the link, unless its name is already used (committed link or file)
+		if [ -e "$_ALIAS_LINK" ] || [ -L "$_ALIAS_LINK" ]; then
+			continue
+		fi
+		echo "$(ansi dim)> $_ALIAS_LINK$(ansi reset)"
+		ln -sn "$_ALIAS_BASE" "$_ALIAS_LINK"
+		if [ $? -ne 0 ]; then
+			abort "Unable to create the symlink '$(ansi dim)$_ALIAS_LINK$(ansi reset)'."
+		fi
+	done
+}
+
 # _install_crontab()
 # Install new crontab file.
 _install_crontab() {
