gitacross 2.1.0__tar.gz → 2.3.0__tar.gz

{gitacross-2.1.0/src/gitacross.egg-info → gitacross-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitacross
-Version: 2.1.0
+Version: 2.3.0
 Summary: Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines.
 Author: Matthew Deik
 License-Expression: MIT
@@ -112,7 +112,7 @@ gitacross --config config.yml --lint
 gitacross --config config.yml
 ```
 
-Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
+Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project-name my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
 
 ## How it works
 
@@ -157,6 +157,13 @@ A config file starts with a `projects` list — each entry is one mirror and nee
 
 Tokens use `${VAR}` syntax — resolved from environment variables.
 
+For local **targets**, the `path` does not have to exist yet: if the directory is
+missing or is not already a git repository, GitAcross creates the directory and
+runs `git init` there before committing. If a repository already exists at that
+path it is opened as-is — existing git metadata is never re-initialised or
+overwritten (bare repositories and broken `.git` markers are refused with an
+error). Local **sources** must point at an existing git repository.
+
 | Option | Description |
 |---|---|
 | [`enabled`](#enabled) | Disable a project without deleting it |
@@ -176,11 +183,11 @@ Copy the source release notes/body to the target release. Default `true`. Set at
 
 #### `release_description`
 
-Format the target release notes from a template (aliases: `release_notes_template`, `description_template`). Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
+Format the target release notes from a template. Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
 
 #### `commit_message`
 
-Custom commit message for the target commits (alias: `commit_template`). Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
+Custom commit message for the target commits. Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
 
 #### `sync_assets`
 
@@ -436,13 +443,13 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
 |---|---|
 | `--config PATH` | Config file to use (required) |
-| `--project NAME` | Sync only this project |
+| `--project-name NAME` | Sync only the project with this name |
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
@@ -477,7 +484,7 @@ for r in results:
 # Preview only — nothing is committed or pushed
 results = gitacross.run(
     "config.yml",
-    project="my-project",
+    project_name="my-project",
     dry_run=True,
     work_dir="/data/custom_dir",
 )
@@ -501,9 +508,9 @@ results = gitacross.run("config.yml", reset=True)
 ```python
 config = gitacross.Config("config.yml")
 
-for project in config.projects:
-    if project.enabled:
-        gitacross.sync_project(project, ".gitsync", dry_run=False)
+for project_config in config.projects:
+    if project_config.enabled:
+        gitacross.sync_project(project_config, ".gitsync", dry_run=False)
 ```
 
 </details>
@@ -513,7 +520,7 @@ for project in config.projects:
 
 ```python
 # ${VAR} tokens still resolve from the environment
-project = gitacross.ProjectConfig({
+project_config = gitacross.ProjectConfig({
     "name": "my-project",
     "source": {
         "type": "gitea",
@@ -528,7 +535,7 @@ project = gitacross.ProjectConfig({
         "token": "${GITHUB_TOKEN}",
     },
 })
-gitacross.sync_project(project, ".gitsync")
+gitacross.sync_project(project_config, ".gitsync")
 ```
 
 </details>
@@ -573,16 +580,16 @@ All public symbols are importable directly from `gitacross`:
 
 | Symbol | What it does |
 |---|---|
-| `run(config, project=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
-| `sync_project(project, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
+| `run(config, project_name=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
+| `sync_project(project_config, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project_config.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
 | `lint_config(config, print_output=True)` | Lint a config (path or open file object) → `LintReport` |
 | `fix_config(config, write_back=True, print_output=True)` | Fix misplaced/redundant options (path only — writes back to the file) → `FixReport` |
 | `Config(config_source)` | Load a config from a path or open file object; exposes `.projects`. `Config.from_yaml_string(content)` loads a config from raw YAML text (`str` or `bytes`) — no file or stream needed |
 | `ProjectConfig(raw)` | Build one mirror project from a raw config dict (see the “No config file” example). Fields: `name`, `enabled`, `source`, `target`, `renderer`, `retry`, `preserve_description`, `sync_assets`, `stream_assets`, `commit_message`, `release_description` |
 | `ConfigLinter()` | Collect lint issues programmatically: `lint_file(config)`, `lint_yaml_string(content)`; results accumulate in `.issues` |
 | `ConfigFixer()` | Fix a config programmatically: `fix_yaml_string(content)` → `FixReport`; actions recorded in `.fixes` |
-| `LintIssue(severity, message, project=None, key=None)` | One lint finding |
-| `FixIssue(message, project=None)` | One applied fix |
+| `LintIssue(severity, message, project_name=None, key=None)` | One lint finding |
+| `FixIssue(message, project_name=None)` | One applied fix |
 | `LintReport(issues)` | Lint results: `.issues`, `.errors`, `.warnings`, `.redundant`, `.is_valid`, `.format_text()` |
 | `FixReport(fixes, content, is_valid, error=None)` | Fix results: `.fixes`, `.content`, `.is_valid`, `.error`, `.format_text()` |
 | `LintSeverity` | Severity levels used by `LintIssue`: `LintSeverity.ERROR`, `LintSeverity.WARNING`, `LintSeverity.REDUNDANT` |

{gitacross-2.1.0 → gitacross-2.3.0}/README.md

@@ -83,7 +83,7 @@ gitacross --config config.yml --lint
 gitacross --config config.yml
 ```
 
-Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
+Run it again later — releases that were already synced are skipped, so nothing is duplicated. Use `--project-name my-project` to sync a single project. See [CLI](#cli) for all flags, or the [Python API](#python-api) to drive GitAcross from code.
 
 ## How it works
 
@@ -128,6 +128,13 @@ A config file starts with a `projects` list — each entry is one mirror and nee
 
 Tokens use `${VAR}` syntax — resolved from environment variables.
 
+For local **targets**, the `path` does not have to exist yet: if the directory is
+missing or is not already a git repository, GitAcross creates the directory and
+runs `git init` there before committing. If a repository already exists at that
+path it is opened as-is — existing git metadata is never re-initialised or
+overwritten (bare repositories and broken `.git` markers are refused with an
+error). Local **sources** must point at an existing git repository.
+
 | Option | Description |
 |---|---|
 | [`enabled`](#enabled) | Disable a project without deleting it |
@@ -147,11 +154,11 @@ Copy the source release notes/body to the target release. Default `true`. Set at
 
 #### `release_description`
 
-Format the target release notes from a template (aliases: `release_notes_template`, `description_template`). Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
+Format the target release notes from a template. Placeholders: `{body}`, `{description}`, `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`.
 
 #### `commit_message`
 
-Custom commit message for the target commits (alias: `commit_template`). Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
+Custom commit message for the target commits. Default: `"Release {tag}"` or `"Sync commit {short_sha}"`. Placeholders: `{tag}`, `{commit_sha}`, `{short_sha}`, `{project_name}`, `{name}`, `{source_date}`, `{body}`, `{description}`.
 
 #### `sync_assets`
 
@@ -407,13 +414,13 @@ GitAcross can be driven from the command line or called directly from Python.
 ### CLI
 
 ```
-gitacross --config PATH [--project NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
+gitacross --config PATH [--project-name NAME] [--workdir PATH] [--dry-run] [--reset] [--lint] [--fix] [-v]
 ```
 
 | Flag | Description |
 |---|---|
 | `--config PATH` | Config file to use (required) |
-| `--project NAME` | Sync only this project |
+| `--project-name NAME` | Sync only the project with this name |
 | `--workdir PATH` | Where state and cache live (default: `.gitsync`) |
 | `--dry-run` | Preview changes without committing or pushing |
 | `--reset` | Clear saved state and cache before running (fresh start) |
@@ -448,7 +455,7 @@ for r in results:
 # Preview only — nothing is committed or pushed
 results = gitacross.run(
     "config.yml",
-    project="my-project",
+    project_name="my-project",
     dry_run=True,
     work_dir="/data/custom_dir",
 )
@@ -472,9 +479,9 @@ results = gitacross.run("config.yml", reset=True)
 ```python
 config = gitacross.Config("config.yml")
 
-for project in config.projects:
-    if project.enabled:
-        gitacross.sync_project(project, ".gitsync", dry_run=False)
+for project_config in config.projects:
+    if project_config.enabled:
+        gitacross.sync_project(project_config, ".gitsync", dry_run=False)
 ```
 
 </details>
@@ -484,7 +491,7 @@ for project in config.projects:
 
 ```python
 # ${VAR} tokens still resolve from the environment
-project = gitacross.ProjectConfig({
+project_config = gitacross.ProjectConfig({
     "name": "my-project",
     "source": {
         "type": "gitea",
@@ -499,7 +506,7 @@ project = gitacross.ProjectConfig({
         "token": "${GITHUB_TOKEN}",
     },
 })
-gitacross.sync_project(project, ".gitsync")
+gitacross.sync_project(project_config, ".gitsync")
 ```
 
 </details>
@@ -544,16 +551,16 @@ All public symbols are importable directly from `gitacross`:
 
 | Symbol | What it does |
 |---|---|
-| `run(config, project=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
-| `sync_project(project, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
+| `run(config, project_name=None, dry_run=False, reset=False, work_dir=".gitsync")` | **Primary entry point.** Sync from a config — a `Config` instance, a path, or an open file object
+| `sync_project(project_config, work_dir=".gitsync", dry_run=False)` | Sync one project's new releases (respects `project_config.enabled`); state and cache live in `work_dir`. Returns dicts with `tag`, `source_commit`, `target_commit`, `source_date` |
 | `lint_config(config, print_output=True)` | Lint a config (path or open file object) → `LintReport` |
 | `fix_config(config, write_back=True, print_output=True)` | Fix misplaced/redundant options (path only — writes back to the file) → `FixReport` |
 | `Config(config_source)` | Load a config from a path or open file object; exposes `.projects`. `Config.from_yaml_string(content)` loads a config from raw YAML text (`str` or `bytes`) — no file or stream needed |
 | `ProjectConfig(raw)` | Build one mirror project from a raw config dict (see the “No config file” example). Fields: `name`, `enabled`, `source`, `target`, `renderer`, `retry`, `preserve_description`, `sync_assets`, `stream_assets`, `commit_message`, `release_description` |
 | `ConfigLinter()` | Collect lint issues programmatically: `lint_file(config)`, `lint_yaml_string(content)`; results accumulate in `.issues` |
 | `ConfigFixer()` | Fix a config programmatically: `fix_yaml_string(content)` → `FixReport`; actions recorded in `.fixes` |
-| `LintIssue(severity, message, project=None, key=None)` | One lint finding |
-| `FixIssue(message, project=None)` | One applied fix |
+| `LintIssue(severity, message, project_name=None, key=None)` | One lint finding |
+| `FixIssue(message, project_name=None)` | One applied fix |
 | `LintReport(issues)` | Lint results: `.issues`, `.errors`, `.warnings`, `.redundant`, `.is_valid`, `.format_text()` |
 | `FixReport(fixes, content, is_valid, error=None)` | Fix results: `.fixes`, `.content`, `.is_valid`, `.error`, `.format_text()` |
 | `LintSeverity` | Severity levels used by `LintIssue`: `LintSeverity.ERROR`, `LintSeverity.WARNING`, `LintSeverity.REDUNDANT` |

{gitacross-2.1.0 → gitacross-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gitacross"
-version = "2.1.0"
+version = "2.3.0"
 description = "Mirror releases and git commits across platforms (Gitea, GitHub, local) with transform pipelines."
 readme = "README.md"
 requires-python = ">=3.8"

{gitacross-2.1.0 → gitacross-2.3.0}/src/gitacross/__init__.py

@@ -8,13 +8,13 @@ Quickstart (Python API)::
     results = gitacross.run("config.yml")
 
     # Sync a single project with dry-run mode:
-    results = gitacross.run("config.yml", project="my-mirror", dry_run=True)
+    results = gitacross.run("config.yml", project_name="my-mirror", dry_run=True)
 
     # Lower-level: build objects yourself for full control:
     config = gitacross.Config("config.yml")
-    for project in config.projects:
-        if project.enabled:
-            gitacross.sync_project(project, ".gitsync")
+    for project_config in config.projects:
+        if project_config.enabled:
+            gitacross.sync_project(project_config, ".gitsync")
 
     # Lint / fix a config file:
     report = gitacross.lint_config("config.yml")

{gitacross-2.1.0 → gitacross-2.3.0}/src/gitacross/cli.py

@@ -26,7 +26,7 @@ def main():
 
     parser = argparse.ArgumentParser(description="Sync releases from source to target")
     _ = parser.add_argument("--config", required=True, help="Path to config.yml")
-    _ = parser.add_argument("--project", help="Sync only this project (by name)")
+    _ = parser.add_argument("--project-name", help="Sync only this project (by name)")
     _ = parser.add_argument(
         "--dry-run", action="store_true", help="Print changes without pushing"
     )
@@ -58,7 +58,7 @@ def main():
     config_path = Path(cast(str, args.config))
     fix_flag = cast(bool, args.fix)
     lint_flag = cast(bool, args.lint)
-    project_filter = None if args.project is None else cast(str, args.project)
+    project_name = None if args.project_name is None else cast(str, args.project_name)
     dry_run_flag = cast(bool, args.dry_run)
     reset_flag = cast(bool, args.reset)
     workdir = cast(str, args.workdir)
@@ -92,7 +92,7 @@ def main():
     try:
         results = run(
             config_path,
-            project=project_filter,
+            project_name=project_name,
             dry_run=dry_run_flag,
             reset=reset_flag,
             work_dir=workdir,

{gitacross-2.1.0 → gitacross-2.3.0}/src/gitacross/config.py

@@ -22,10 +22,7 @@ VALID_PROJECT_KEYS = {
     "sync_assets",
     "stream_assets",
     "commit_message",
-    "commit_template",
     "release_description",
-    "release_notes_template",
-    "description_template",
 }
 
 KNOWN_SOURCE_KEYS = {
@@ -256,15 +253,10 @@ class ProjectConfig:
         self.stream_assets = bool(raw.get("stream_assets", False))
 
         # commit_message — project-level commit message template (e.g. "chore(sync): {tag}")
-        self.commit_message = raw.get("commit_message") or raw.get("commit_template") or None
+        self.commit_message = raw.get("commit_message") or None
 
         # release_description — project-level release description template
-        self.release_description = (
-            raw.get("release_description")
-            or raw.get("release_notes_template")
-            or raw.get("description_template")
-            or None
-        )
+        self.release_description = raw.get("release_description") or None
 
     def __repr__(self):
         return (
@@ -309,9 +301,8 @@ def _cascade(raw_project, raw_source, raw_target, keys, default):
     """Return the first value found for any of *keys* across project, source, target.
 
     Lookup order: project-level first (highest priority), then source-level,
-    then target-level, then *default*.  All alias keys are checked at each
-    level before moving to the next — so a project-level alias wins over a
-    source-level primary key.
+    then target-level, then *default*. The first *key* present at the first
+    level wins — so a project-level value beats a source-level one.
     """
     for raw in (raw_project, raw_source, raw_target):
         for k in keys:

{gitacross-2.1.0 → gitacross-2.3.0}/src/gitacross/git.py

@@ -37,9 +37,16 @@ def _log_git_stderr(command, returncode, stderr, level):
         )
 
 
-def _git(*args, check=True, input_data=None, text=True, env=None):
-    cmd = ["git"] + [str(a) for a in args]
-    logger.debug("> git %s", _redact(" ".join(str(a) for a in args)))
+def _git(*args, check=True, input_data=None, text=True, env=None, safe_dir=None):
+    cmd = ["git"]
+    if safe_dir:
+        # Git refuses to operate in a repository owned by another user
+        # ("dubious ownership"). The bare mirrors under the cache dir are
+        # created and managed by gitacross itself, so whitelist exactly that
+        # directory for this one invocation via -c — never written to a config.
+        cmd += ["-c", f"safe.directory={Path(safe_dir).resolve()}"]
+    cmd += [str(a) for a in args]
+    logger.debug("> git %s", _redact(" ".join(str(a) for a in cmd[1:])))
     try:
         result = subprocess.run(
             cmd,
@@ -56,6 +63,12 @@ def _git(*args, check=True, input_data=None, text=True, env=None):
             if isinstance(part, str):
                 e.cmd[i] = _redact(part)
         raise
+    except FileNotFoundError as exc:
+        # subprocess can't find the `git` binary at all — give a clear error
+        # instead of the raw "[Errno 2] No such file or directory: 'git'".
+        raise ValueError(
+            "git executable not found — install Git and make sure it is on PATH."
+        ) from exc
     if result.returncode != 0:
         # check=False path — callers inspect the return code themselves
         _log_git_stderr(args[0], result.returncode, result.stderr, level=logging.DEBUG)
@@ -87,34 +100,117 @@ class GitRepo:
         path = Path(dest)
         if path.exists():
             # Update remote URL *before* fetching so token rotation takes effect
-            current = _git("-C", str(path), "remote", "get-url", "origin", check=False)
+            current = _git(
+                "-C", str(path), "remote", "get-url", "origin",
+                check=False, safe_dir=path,
+            )
             if current.returncode == 0 and current.stdout.strip() != url:
-                _ = _git("-C", str(path), "remote", "set-url", "origin", url)
+                _ = _git(
+                    "-C", str(path), "remote", "set-url", "origin", url,
+                    safe_dir=path,
+                )
                 logger.info("Updated remote URL for mirror at %s", dest)
-            _ = _git("-C", str(path), "fetch", "--tags", "--prune", "origin")
+            _ = _git(
+                "-C", str(path), "fetch", "--tags", "--prune", "origin",
+                safe_dir=path,
+            )
             logger.info("Updated mirror at %s", dest)
         else:
             path.parent.mkdir(parents=True, exist_ok=True)
-            _ = _git("clone", "--mirror", url, str(path))
+            _ = _git("clone", "--mirror", url, str(path), safe_dir=path)
             logger.info("Cloned mirror from %s", _redact(url))
         # Ensure author identity for automated commits
-        _ = _git("-C", str(path), "config", "user.name", "GitAcross")
-        _ = _git("-C", str(path), "config", "user.email", "sync@gitacross")
+        _ = _git("-C", str(path), "config", "user.name", "GitAcross", safe_dir=path)
+        _ = _git("-C", str(path), "config", "user.email", "sync@gitacross", safe_dir=path)
         return cls(path, is_bare=True)
 
     @classmethod
     def local(cls, path):
-        """Open an existing local git repository."""
+        """Open an existing local git repository.
+
+        *path* must be the root of its own git working tree. Git resolves a
+        path that merely lives *inside* a repository to the nearest enclosing
+        repository, so without this check a configured path that is not itself
+        a git repository would silently commit to and reset that enclosing
+        repo — e.g. the directory the tool is being run from — instead of the
+        configured location.
+        """
         p = Path(path)
-        result = _git("-C", str(p), "rev-parse", "--git-dir")
-        git_dir = p / result.stdout.strip()
-        if not git_dir.exists():
+        result = _git("-C", str(p), "rev-parse", "--show-toplevel", check=False)
+        if result.returncode != 0:
             raise ValueError(f"Not a git repository: {path}")
-        return cls(git_dir, is_bare=False)
+        root = Path(result.stdout.strip())
+        if Path(p).resolve() != root.resolve():
+            raise ValueError(
+                f"Not a git repository: {path} — it is inside the git repository "
+                + f"'{root}'. A local endpoint path must point at a repository "
+                + f"root; run 'git init' in {path} or point the path at {root}."
+            )
+        git_dir = _git("-C", str(root), "rev-parse", "--absolute-git-dir")
+        return cls(Path(git_dir.stdout.strip()), is_bare=False)
+
+    @classmethod
+    def ensure_local(cls, path):
+        """Open a local git repository at *path*, creating it if necessary.
+
+        Unlike :meth:`local`, a missing directory or a plain directory that is
+        not yet a git repository is accepted: the directory is created
+        (including parents) and ``git init`` is run there. Used for local
+        *targets*, which receive commits. Local *sources* still go through
+        :meth:`local` so a misconfigured source path is reported instead of
+        silently yielding an empty repository.
+
+        An existing repository is opened as-is and never re-initialised. If
+        *path* already holds git metadata that cannot be used as a working tree
+        (a bare repository, a git-internal directory, or a broken ``.git``
+        marker), a :class:`ValueError` is raised instead of overwriting it.
+        """
+        if not path or not str(path).strip():
+            raise ValueError(
+                "Local target path is empty — set 'path' to the directory where "
+                + "the mirrored repository should live."
+            )
+        try:
+            return cls.local(path)
+        except ValueError:
+            pass
+
+        # Only auto-initialise when the directory is genuinely not a git
+        # repository yet — never run `git init` over existing git metadata
+        # (re-initialising a bare repo pollutes it with a nested .git).
+        p = Path(path)
+        if p.exists() and not p.is_dir():
+            raise ValueError(f"Local target path is not a directory: {path}")
+        if (p / ".git").exists():
+            raise ValueError(
+                f"Not initialising {path}: it already contains a '.git' entry "
+                + "that is not a usable working tree. Refusing to overwrite it — "
+                + "fix or remove that repository, or point the local target at a "
+                + "missing or empty directory."
+            )
+        if (p / "HEAD").is_file() and (p / "objects").is_dir():
+            raise ValueError(
+                f"Not initialising {path}: it is a bare git repository or git's "
+                + "internal directory. Local targets need a working tree, and "
+                + "existing repositories are never re-initialised."
+            )
+        p.mkdir(parents=True, exist_ok=True)
+        _ = _git("init", str(p))
+        logger.info("Initialised git repository at %s", p)
+        return cls.local(path)
 
     def _g(self, *args, text=True, env=None, **kwargs):
         """Run git command with --git-dir set."""
-        return _git("--git-dir", str(self.git_dir), *args, text=text, env=env, **kwargs)
+        return _git(
+            "--git-dir",
+            str(self.git_dir),
+            *args,
+            text=text,
+            env=env,
+            # Mirrors are gitacross-managed; whitelist them for the ownership check.
+            safe_dir=self.git_dir if self.is_bare else None,
+            **kwargs,
+        )
 
     def _gw(self, work_dir, *args, env=None, **kwargs):
         """Run git command with --git-dir and --work-tree set."""
@@ -125,6 +221,8 @@ class GitRepo:
             str(work_dir),
             *args,
             env=env,
+            # Mirrors are gitacross-managed; whitelist them for the ownership check.
+            safe_dir=self.git_dir if self.is_bare else None,
             **kwargs,
         )