Skip to content

πŸ’« Toolkit to help you get started with SDD or any other process!

feat(init): scaffold managed .specify/.gitignore (#4000)

Manfred Riem40037b1aca12
diff --git a/docs/reference/core.md b/docs/reference/core.md
index 3318264b4..fdf0b80e7 100644
--- a/docs/reference/core.md
+++ b/docs/reference/core.md
@@ -57,6 +57,8 @@ specify init my-project --integration copilot --preset compliance
> **Two resolution axes.** `SPECIFY_INIT_DIR` selects the **project** (which directory contains `.specify/`); `SPECIFY_FEATURE_DIRECTORY` / `.specify/feature.json` select the **feature** within that project. They are independent β€” project first, then feature.
+> **Version control.** `specify init` scaffolds a managed `.specify/.gitignore` that excludes machine-local state β€” `feature.json` (the current-feature pointer, rewritten on every feature switch) and per-machine extension `extensions/*/local-config.yml` overrides β€” while leaving everything else under `.specify/` (constitution, templates, scripts, extension config) shareable so teams stay aligned. Like the rest of `.specify/`'s shared scripts and templates, the file is tracked in the shared-infrastructure manifest: your edits are preserved on re-init and `specify init --here --force` restores the managed content. It is intentionally left in place by `specify integration uninstall`, which only removes the uninstalled agent's own files.
+
> **Symlinked project roots.** `SPECIFY_INIT_DIR` relocates *where* the project is, not *how* a command treats symlinks: each command keeps its existing cwd-path stance. Commands that traverse and write project files through broad input paths (`bundle`, `workflow run <file>`) refuse a symlinked `.specify/` to preserve write confinement. Other project-scoped commands keep their existing behavior when `SPECIFY_INIT_DIR` points at a project root, which may include following a symlinked `.specify/`.
## Check Installed Tools
diff --git a/src/specify_cli/shared_infra.py b/src/specify_cli/shared_infra.py
index 1c8d727d7..c8d04c9fd 100644
--- a/src/specify_cli/shared_infra.py
+++ b/src/specify_cli/shared_infra.py
@@ -16,6 +16,22 @@ from .integrations.manifest import IntegrationManifest
logger = logging.getLogger(__name__)
+# Managed ``.specify/.gitignore``. Keeps machine-local Spec Kit state out of
+# version control while leaving shareable project files (specs, constitution,
+# templates, scripts, extension config) tracked. Patterns are relative to the
+# ``.specify/`` directory the file lives in.
+SPECIFY_GITIGNORE_CONTENT = """\
+# Machine-local Spec Kit state β€” not meant to be shared.
+# Managed by the Specify CLI; safe to edit (your changes are preserved on refresh).
+
+# Local pointer to the current feature directory. Rewritten every time you
+# switch features, so it is per-checkout state rather than something to share.
+feature.json
+
+# Per-machine extension config overrides.
+extensions/*/local-config.yml
+"""
+
# Matches a SHA-256 digest in its normalized form: exactly 64 hexadecimal
# characters. Callers lowercase the declared value before matching (see
# ``expected_hex = raw.lower()`` below), so an uppercase digest is accepted and
@@ -608,6 +624,36 @@ def install_shared_infra(
)
planned_templates.append((dst, rel, content))
+ # Managed ``.specify/.gitignore`` β€” keeps machine-local state (the
+ # ``feature.json`` pointer and per-machine ``local-config.yml`` overrides)
+ # out of git while leaving everything else shareable. Routed through the
+ # same overwrite/skip/preserve policy as templates so ``--force`` refreshes
+ # it and user edits are preserved. Like every other shared-infra file it is
+ # tracked in ``speckit.manifest.json`` (not the per-integration manifest) and
+ # is therefore intentionally left in place by ``integration uninstall``.
+ specify_dir = project_path / ".specify"
+ if _ensure_or_bucket_dir(specify_dir):
+ gitignore_dst = specify_dir / ".gitignore"
+ gitignore_rel = gitignore_dst.relative_to(project_path).as_posix()
+ seen_rels.add(gitignore_rel)
+ if _safe_dest_or_bucket(gitignore_dst, gitignore_rel):
+ write, bucket = _decide_overwrite(gitignore_rel, gitignore_dst)
+ if write:
+ planned_templates.append(
+ (gitignore_dst, gitignore_rel, SPECIFY_GITIGNORE_CONTENT)
+ )
+ elif bucket == "preserved":
+ preserved_user_files.append(gitignore_rel)
+ else:
+ skipped_files.append(gitignore_rel)
+ if gitignore_dst.is_file() and gitignore_rel not in prior_hashes:
+ try:
+ manifest.record_existing(gitignore_rel, recovered=True)
+ except (OSError, ValueError) as exc:
+ console.print(
+ f"[yellow]⚠[/yellow] could not record {gitignore_rel} in manifest: {exc}"
+ )
+
for dst_path, rel, content, mode in planned_copies:
if not _ensure_or_bucket_dir(dst_path.parent):
continue
diff --git a/tests/integrations/test_integration_base_markdown.py b/tests/integrations/test_integration_base_markdown.py
index aa906c440..310a0347d 100644
--- a/tests/integrations/test_integration_base_markdown.py
+++ b/tests/integrations/test_integration_base_markdown.py
@@ -238,6 +238,7 @@ class MarkdownIntegrationTests:
files.append(".specify/init-options.json")
files.append(f".specify/integrations/{self.KEY}.manifest.json")
files.append(".specify/integrations/speckit.manifest.json")
+ files.append(".specify/.gitignore")
if script_variant == "sh":
for name in ["check-prerequisites.sh", "common.sh", "create-new-feature.sh",
diff --git a/tests/integrations/test_integration_base_skills.py b/tests/integrations/test_integration_base_skills.py
index 1f29e1222..d06422401 100644
--- a/tests/integrations/test_integration_base_skills.py
+++ b/tests/integrations/test_integration_base_skills.py
@@ -484,6 +484,7 @@ class SkillsIntegrationTests:
".specify/integration.json",
f".specify/integrations/{self.KEY}.manifest.json",
".specify/integrations/speckit.manifest.json",
+ ".specify/.gitignore",
".specify/memory/.constitution-template.json",
".specify/memory/constitution.md",
]
diff --git a/tests/integrations/test_integration_base_toml.py b/tests/integrations/test_integration_base_toml.py
index 8a7344e4b..5469f1350 100644
--- a/tests/integrations/test_integration_base_toml.py
+++ b/tests/integrations/test_integration_base_toml.py
@@ -488,6 +488,7 @@ class TomlIntegrationTests:
files.append(".specify/init-options.json")
files.append(f".specify/integrations/{self.KEY}.manifest.json")
files.append(".specify/integrations/speckit.manifest.json")
+ files.append(".specify/.gitignore")
if script_variant == "sh":
for name in [
diff --git a/tests/integrations/test_integration_base_yaml.py b/tests/integrations/test_integration_base_yaml.py
index f3e39b24f..3312dfec0 100644
--- a/tests/integrations/test_integration_base_yaml.py
+++ b/tests/integrations/test_integration_base_yaml.py
@@ -402,6 +402,7 @@ class YamlIntegrationTests:
files.append(".specify/init-options.json")
files.append(f".specify/integrations/{self.KEY}.manifest.json")
files.append(".specify/integrations/speckit.manifest.json")
+ files.append(".specify/.gitignore")
if script_variant == "sh":
for name in [
diff --git a/tests/integrations/test_integration_cline.py b/tests/integrations/test_integration_cline.py
index f1abdedc8..5bd25c7d8 100644
--- a/tests/integrations/test_integration_cline.py
+++ b/tests/integrations/test_integration_cline.py
@@ -185,6 +185,7 @@ class TestClineIntegration(MarkdownIntegrationTests):
files.append(".specify/init-options.json")
files.append(f".specify/integrations/{self.KEY}.manifest.json")
files.append(".specify/integrations/speckit.manifest.json")
+ files.append(".specify/.gitignore")
if script_variant == "sh":
for name in [
diff --git a/tests/integrations/test_integration_copilot.py b/tests/integrations/test_integration_copilot.py
index 7a680b7dd..b75eac971 100644
--- a/tests/integrations/test_integration_copilot.py
+++ b/tests/integrations/test_integration_copilot.py
@@ -274,6 +274,7 @@ class TestCopilotCommandsMode:
".specify/init-options.json",
".specify/integrations/copilot.manifest.json",
".specify/integrations/speckit.manifest.json",
+ ".specify/.gitignore",
".specify/scripts/bash/check-prerequisites.sh",
".specify/scripts/bash/common.sh",
".specify/scripts/bash/create-new-feature.sh",
@@ -337,6 +338,7 @@ class TestCopilotCommandsMode:
".specify/init-options.json",
".specify/integrations/copilot.manifest.json",
".specify/integrations/speckit.manifest.json",
+ ".specify/.gitignore",
".specify/scripts/powershell/check-prerequisites.ps1",
".specify/scripts/powershell/common.ps1",
".specify/scripts/powershell/create-new-feature.ps1",
@@ -847,6 +849,7 @@ class TestCopilotSkillsMode:
".specify/integration.json",
".specify/integrations/copilot.manifest.json",
".specify/integrations/speckit.manifest.json",
+ ".specify/.gitignore",
# Scripts (sh)
".specify/scripts/bash/check-prerequisites.sh",
".specify/scripts/bash/common.sh",
diff --git a/tests/integrations/test_integration_generic.py b/tests/integrations/test_integration_generic.py
index 202f7ab3d..fab64a9f0 100644
--- a/tests/integrations/test_integration_generic.py
+++ b/tests/integrations/test_integration_generic.py
@@ -342,6 +342,7 @@ class TestGenericIntegration:
".specify/integration.json",
".specify/integrations/generic.manifest.json",
".specify/integrations/speckit.manifest.json",
+ ".specify/.gitignore",
".specify/memory/.constitution-template.json",
".specify/memory/constitution.md",
".specify/scripts/bash/check-prerequisites.sh",
@@ -399,6 +400,7 @@ class TestGenericIntegration:
".specify/integration.json",
".specify/integrations/generic.manifest.json",
".specify/integrations/speckit.manifest.json",
+ ".specify/.gitignore",
".specify/memory/.constitution-template.json",
".specify/memory/constitution.md",
".specify/scripts/powershell/check-prerequisites.ps1",
diff --git a/tests/test_shared_infra_gitignore.py b/tests/test_shared_infra_gitignore.py
new file mode 100644
index 000000000..4badeaa8e
--- /dev/null
+++ b/tests/test_shared_infra_gitignore.py
@@ -0,0 +1,103 @@
+"""Tests for the managed ``.specify/.gitignore`` written by shared-infra install.
+
+The Specify CLI scaffolds a ``.specify/.gitignore`` so machine-local Spec Kit
+state (the ``feature.json`` current-feature pointer and per-machine extension
+``local-config.yml`` overrides) stays out of version control while everything
+else under ``.specify/`` remains shareable. These tests pin that behaviour:
+the file is created and manifest-tracked, its patterns actually make git ignore
+the intended paths, user edits are preserved on a plain re-run, and ``--force``
+restores the managed content.
+"""
+
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from specify_cli import _install_shared_infra
+from specify_cli.shared_infra import SPECIFY_GITIGNORE_CONTENT
+
+
+def _install(project: Path, **kwargs) -> None:
+ (project / ".specify").mkdir(parents=True, exist_ok=True)
+ _install_shared_infra(project, "sh", **kwargs)
+
+
+def test_gitignore_is_written_and_tracked(tmp_path: Path) -> None:
+ project = tmp_path / "proj"
+ _install(project)
+
+ gitignore = project / ".specify" / ".gitignore"
+ assert gitignore.is_file()
+
+ content = gitignore.read_text(encoding="utf-8")
+ assert "feature.json" in content
+ assert "extensions/*/local-config.yml" in content
+
+ manifest = json.loads(
+ (project / ".specify" / "integrations" / "speckit.manifest.json").read_text(
+ encoding="utf-8"
+ )
+ )
+ assert ".specify/.gitignore" in manifest.get("files", {})
+
+
[email protected](shutil.which("git") is None, reason="git not available")
+def test_git_ignores_the_intended_paths(tmp_path: Path) -> None:
+ project = tmp_path / "proj"
+ project.mkdir()
+ subprocess.run(["git", "init", "-q"], cwd=project, check=True)
+
+ _install(project)
+
+ (project / ".specify" / "feature.json").write_text("{}", encoding="utf-8")
+ ext_local = project / ".specify" / "extensions" / "git" / "local-config.yml"
+ ext_local.parent.mkdir(parents=True, exist_ok=True)
+ ext_local.write_text("x\n", encoding="utf-8")
+
+ for rel in (
+ ".specify/feature.json",
+ ".specify/extensions/git/local-config.yml",
+ ):
+ result = subprocess.run(
+ ["git", "check-ignore", rel],
+ cwd=project,
+ capture_output=True,
+ text=True,
+ )
+ assert result.returncode == 0, f"{rel} was not ignored"
+
+ # A shareable file under .specify/ must NOT be ignored.
+ tracked = subprocess.run(
+ ["git", "check-ignore", ".specify/memory/constitution.md"],
+ cwd=project,
+ capture_output=True,
+ text=True,
+ )
+ assert tracked.returncode == 1
+
+
+def test_user_edits_preserved_by_default(tmp_path: Path) -> None:
+ project = tmp_path / "proj"
+ _install(project)
+
+ gitignore = project / ".specify" / ".gitignore"
+ gitignore.write_text("# my customization\n", encoding="utf-8")
+
+ _install(project) # plain re-run must not clobber user edits
+ assert gitignore.read_text(encoding="utf-8") == "# my customization\n"
+
+
+def test_force_restores_managed_content(tmp_path: Path) -> None:
+ project = tmp_path / "proj"
+ _install(project)
+
+ gitignore = project / ".specify" / ".gitignore"
+ gitignore.write_text("# my customization\n", encoding="utf-8")
+
+ _install(project, force=True)
+ assert gitignore.read_text(encoding="utf-8") == SPECIFY_GITIGNORE_CONTENT