add docs

Author: maganaluis

copier/_cli.py

@@ -165,7 +165,7 @@ def __init__(self, executable: PathLike[str]) -> None:
     resolve_commit_to_sha = cli.Flag(
         ["--resolve-commit-to-sha"],
         default=False,
-        help="Store SHA commit hash instead of git ref in answers file (prevents issues with moving tags)",
+        help="Store SHA commit hash instead of git ref in answers file for immutable references",
     )
 
     @cli.switch(  # type: ignore[misc]

copier/_main.py

@@ -219,8 +219,8 @@ class Worker:
 
         resolve_commit_to_sha:
             When `True`, store SHA commit hash instead of git ref (tag/branch)
-            in the answers file. This prevents issues with moving/floating tags
-            that may point to different commits over time.
+            in the answers file. This provides an immutable reference to the
+            exact template version used.
     """
 
     # NOTE: attributes are fully documented in [creating.md](../docs/creating.md)
@@ -349,7 +349,7 @@ def _answers_to_remember(self) -> Mapping[str, Any]:
             should_resolve = self.template.resolve_commit_to_sha
 
         if should_resolve and self.template.vcs == "git":
-            # Use SHA hash instead of potentially moving ref
+            # Use SHA hash for immutable reference
             commit = self.template.commit_hash or commit
         src = self.template.url
         for key, value in (("_commit", commit), ("_src_path", src)):

docs/configuring.md

@@ -1442,6 +1442,58 @@ Suppress status output.
 
     Not supported in `copier.yml`.
 
+### `resolve_commit_to_sha`
+
+-   Format: `bool`
+-   CLI flags: `--resolve-commit-to-sha`
+-   Default value: `False`
+
+When copying or updating from a Git-versioned template, store the actual SHA commit hash
+in the answers file instead of the Git reference (tag/branch name). This provides an
+immutable reference to the exact template version used, ensuring reproducibility and
+traceability.
+
+Storing SHA hashes instead of symbolic references (tags/branches) is useful for:
+
+-   **Reproducibility**: Ensures the exact same template version can be used across
+    different environments
+-   **Handling mutable references**: References that change over time (like floating
+    tags or branch heads) won't affect existing projects
+
+!!! info
+
+    Template authors can enable this by default in their templates by setting
+    `_resolve_commit_to_sha: true` in `copier.yml`. The CLI flag takes precedence
+    over the template configuration.
+
+!!! example "Usage examples"
+
+    ```shell
+    # Store immutable reference for reproducible builds
+    copier copy --resolve-commit-to-sha --vcs-ref v2.0.0 template destination
+
+    # Working with a development branch
+    copier copy --resolve-commit-to-sha --vcs-ref main template destination
+
+    # Using a floating tag (stores the current SHA, not the tag)
+    copier copy --resolve-commit-to-sha --vcs-ref stable/latest template destination
+    ```
+
+    In all cases, the answers file will contain a SHA hash like `a1b2c3d4e5f6`
+    instead of the symbolic reference, ensuring an immutable reference to the
+    exact template version.
+
+!!! example "Template configuration"
+
+    Template authors can enable this behavior by default:
+
+    ```yaml title="copier.yml"
+    _resolve_commit_to_sha: true
+    ```
+
+    This ensures all projects generated from the template will store immutable
+    SHA references for better reproducibility and traceability.
+
 ### `secret_questions`
 
 -   Format: `List[str]`

docs/faq.md

@@ -215,6 +215,55 @@ $ copier copy -r HEAD ./src ./dst
 ... then you'll notice `new-file.txt` does exist. You passed a specific ref to copy, so
 Copier skips its autodetection and just goes for the `HEAD` you already chose.
 
+## When should I use SHA references instead of tags/branches?
+
+The `--resolve-commit-to-sha` flag stores the actual commit SHA instead of symbolic
+references (tags/branches) in your answers file. This is useful in several scenarios:
+
+### For reproducible builds
+
+When you need to ensure that everyone on your team or CI/CD pipeline uses the exact same
+template version:
+
+```shell
+copier copy --resolve-commit-to-sha --vcs-ref v2.0.0 template destination
+```
+
+### For audit and compliance
+
+When you need immutable records of which exact template version was used for security or
+compliance purposes.
+
+### When working with development branches
+
+If you're using templates from frequently updated branches:
+
+```shell
+copier copy --resolve-commit-to-sha --vcs-ref main template destination
+```
+
+### With floating or moving tags
+
+Some templates use floating tags (like `stable/v1` or `latest`) that get moved to newer
+commits:
+
+```shell
+copier copy --resolve-commit-to-sha --vcs-ref stable/latest template destination
+```
+
+### Template author configuration
+
+Template authors can enable this behavior by default to ensure all projects use
+immutable references:
+
+```yaml title="copier.yml"
+_resolve_commit_to_sha: true
+```
+
+Using SHA references provides better reproducibility, traceability, and security, though
+at the cost of not automatically following tag updates. See [resolve_commit_to_sha][]
+for more details.
+
 ## How to pass credentials to Git?
 
 If you do something like this, and the template supports updates, you'll notice that the

docs/updating.md

@@ -36,6 +36,13 @@ This will read all available Git tags, will compare them using
 before updating. To update to the latest commit, add `--vcs-ref=HEAD`. You can use any
 other Git ref you want.
 
+!!! tip "Using immutable references for updates"
+
+    If your template uses references that may change over time (like floating tags or branch heads),
+    consider using the `--resolve-commit-to-sha` flag when initially copying the template.
+    This stores the actual commit SHA instead of the symbolic reference, ensuring reproducible
+    updates with an immutable reference. See [resolve_commit_to_sha][] for more details.
+
 When updating, Copier will do its best to respect your project evolution by using the
 answers you provided when copied last time. However, sometimes it's impossible for
 Copier to know what to do with a diff code hunk. In those cases, copier handles the