docs: add Image tag format reference doc

website/docs/4-guides/1-deployments/1-deploy-app.md

@@ -140,7 +140,7 @@ This generates tags like:
 `uc deploy` renders the image templates when it loads the Compose file and then uses the resulting names for the build
 and deploy stages.
 
-See the [Image tag format](../../8-compose-file-reference/2-image-tag-format.md) reference for all available template
+See the [Image tag template](../../8-compose-file-reference/2-image-tag-template.md) reference for all available template
 variables and functions.
 
 ### Separate build and deploy steps
@@ -164,7 +164,7 @@ source code and images haven't changed. However, the image tag may still change
 [dynamic tags](#customise-image-tags) based on the Git state (default). In that case, the deploy will likely fail
 because the new tag won't be found on cluster machines.
 
-Use less sensitive dynamic tags or specify the built and pushed images you want to deploy explicitly to avoid this
+Use less sensitive dynamic tags or specify the built and pushed image tags you want to deploy explicitly to avoid this
 issue.
 
 The recommended approach though is to commit all your changes, including the configuration ones, to the repo. Then

website/docs/4-guides/1-deployments/2-deploy-specific-machines.md

@@ -78,7 +78,7 @@ See [Push local images to cluster machines](1-deploy-app.md#push-local-images-to
 
 ## See also
 
-- [Deploy a global service](3-deploy-global-services.md): Deploy one service replica on each cluster machine
 - [Deploy an app](1-deploy-app.md): Deploy from source code or prebuilt images
+- [Deploy a global service](3-deploy-global-services.md): Deploy one service replica on each cluster machine
 - [Compose support matrix](../../8-compose-file-reference/1-support-matrix.md): Supported Compose features and Uncloud
   extensions

website/docs/4-guides/1-deployments/3-deploy-global-services.md

@@ -63,6 +63,7 @@ The default mode is `replicated`, where you specify the number of replicas.
 
 ## See also
 
+- [Deploy an app](1-deploy-app.md): Deploy from source code or prebuilt images
 - [Deploy to specific machines](2-deploy-specific-machines.md): Deploy services to specific machines in your cluster
 - [Compose Specification: deploy.mode](https://github.com/compose-spec/compose-spec/blob/main/deploy.md#mode):
   Compose specification for deployment modes

website/docs/8-compose-file-reference/2-image-tag-format.md

@@ -1,3 +0,0 @@
-# Image tag format
-
-TBD

website/docs/8-compose-file-reference/2-image-tag-template.md

@@ -0,0 +1,151 @@
+# Image tag template
+
+Template syntax for tagging built images.
+
+## Overview
+
+When building service images as part of [`uc build`](../9-cli-reference/uc_build.md) or
+[`uc deploy`](../9-cli-reference/uc_deploy.md) commands, Uncloud automatically generates image tags based on the current
+Git repository state. You can customise the image name and tag format for the built images using the
+[Go template](https://pkg.go.dev/text/template) syntax environment variables.
+
+## Default template
+
+If you **don't specify** an `image` attribute for a service with a `build` section, Uncloud uses the following Go
+template for tagging the built image:
+
+```go
+{{.Project}}/{{.Service}}:{{if.Git.IsRepo}}{{gitdate "2006-01-02-150405"}}.{{gitsha 7}}{{if.Git.IsDirty}}.dirty{{end}}{{else}}{{date "2006-01-02-150405"}}{{end}}
+```
+
+```yaml title="compose.yaml"
+services:
+  web:
+    build: .
+```
+
+This generates image tags as follows:
+
+- Git repository (clean): `myapp/web:2025-10-30-223604.84d33bb`
+- Git repository (with uncommitted changes): `myapp/web:2025-10-30-223604.84d33bb.dirty`
+- Non-Git directory: `myapp/web:2025-10-31-120651`
+
+If you specify only an **image name without a tag** in the `image` attribute, Uncloud appends the tag portion of the
+default template to your image name.
+
+```yaml title="compose.yaml"
+services:
+  web:
+    build: .
+    image: webapp   # → webapp:2025-10-30-223604.84d33bb
+```
+
+If you specify a full **image name with tag** in the `image` attribute, Uncloud uses it as-is without modification.
+
+```yaml title="compose.yaml"
+services:
+  web:
+    build: .
+    image: webapp:1.2.3   # → webapp:1.2.3
+```
+
+## Template functions
+
+### `gitsha [length]`
+
+Returns the Git commit SHA, optionally truncated to the specified length.
+
+```yaml
+image: myapp:{{gitsha 7}}   # → myapp:84d33bb
+image: myapp:{{gitsha}}     # → myapp:84d33bbf0dbb37f96e7df6a5010aed7bab00b089
+```
+
+Returns empty string if the working directory is not a Git repository.
+
+### `gitdate "format" ["timezone"]`
+
+Returns the current Git commit date/time formatted using [Go time layout format](#date-format-reference). The `timezone`
+parameter is optional and defaults to UTC.
+Use [IANA timezone names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) like `America/New_York` or
+`Europe/London`.
+
+```yaml
+image: myapp:{{gitdate "2006-01-02"}}                               # → myapp:2025-10-30
+image: myapp:{{gitdate "20060102-150405"}}                          # → myapp:20251030-223604
+image: myapp:{{gitdate "2006-01-02-150405" "Australia/Brisbane"}}   # → myapp:2025-10-31-083604
+```
+
+Returns empty string if the working directory is not a Git repository.
+
+### `date "format" ["timezone"]`
+
+Returns the current local date/time formatted using [Go time layout format](#date-format-reference). The `timezone`
+parameter is optional and defaults to UTC.
+Use [IANA timezone names](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones) like `America/New_York` or
+`Europe/London`.
+
+```yaml
+image: myapp:{{date "2006-01-02"}}                # → myapp:2025-10-31
+image: myapp:{{date "20060102-150405"}}           # → myapp:20251031-120651
+image: myapp:{{date "20060102-150405" "Local"}}   # → myapp:20251031-220651
+```
+
+### Date format reference
+
+Go uses a reference time (`Mon Jan 2 15:04:05 MST 2006`) for formatting. Replace reference components with desired
+format:
+
+| Component | Reference | Example     |
+|-----------|-----------|-------------|
+| Year      | `2006`    | `2025`      |
+| Month     | `01`      | `10`        |
+| Day       | `02`      | `30`        |
+| Hour      | `15`      | `22` (24hr) |
+| Minute    | `04`      | `36`        |
+| Second    | `05`      | `04`        |
+
+**Common patterns:**
+
+| Format                 | Pattern             | Example             |
+|------------------------|---------------------|---------------------|
+| ISO 8601 date          | `2006-01-02`        | `2025-10-30`        |
+| Compact date           | `20060102`          | `20251030`          |
+| Date with compact time | `2006-01-02-150405` | `2025-10-30-223604`
+
+See Go [time.Format documentation](https://pkg.go.dev/time#Time.Format) for all formatting options.
+
+## Template fields
+
+Access metadata about your project, service, and Git state:
+
+| Field          | Type      | Description                                                        | Example                     |
+|----------------|-----------|--------------------------------------------------------------------|-----------------------------|
+| `.Project`     | string    | Project name from `name` in Compose file or working directory name | `myapp`                     |
+| `.Service`     | string    | Service name                                                       | `web`                       |
+| `.Tag`         | string    | Pre-rendered default tag (without image name)                      | `2025-10-30-223604.84d33bb` |
+| `.Git.IsRepo`  | bool      | Whether working directory is a Git repository                      | `true` or `false`           |
+| `.Git.IsDirty` | bool      | Whether there are uncommitted changes                              | `true` or `false`           |
+| `.Git.SHA`     | string    | Full SHA (40 characters) of the latest Git commit                  | `84d33bb1234567...`         |
+| `.Git.Date`    | time.Time | Git commit date/time (use `gitdate` function to format)            | -                           |
+
+## Environment variable interpolation
+
+Combine templates with environment variable
+[interpolation](https://github.com/compose-spec/compose-spec/blob/main/spec.md#interpolation) using Bash-like syntax.
+The environment variables are expanded before rendering the template.
+
+```yaml
+# CI build number from environment
+image: myapp:{{gitdate "20060102"}}.{{gitsha 7}}.${GITHUB_RUN_ID}   # → myapp:20251030.84d33bb.1234
+
+# With default value
+image: myapp:{{gitsha 7}}.${GITHUB_RUN_ID:-local}   # GITHUB_RUN_ID not set → myapp:84d33bb.local
+```
+
+## See also
+
+- [Deploy an app](../4-guides/1-deployments/1-deploy-app.md): Deploy from source code or prebuilt images
+- [Compose Build Specification](https://github.com/compose-spec/compose-spec/blob/main/build.md)
+- [Compose Specification: image](https://github.com/compose-spec/compose-spec/blob/main/spec.md#image)
+- [Go template documentation](https://pkg.go.dev/text/template)
+- [Go Time.Format documentation](https://pkg.go.dev/time#Time.Format)