gitignorio-cli 0.1.0__py3-none-any.whl

gitignore_cli/file.py

@@ -0,0 +1,137 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from gitignore_cli.mapping import OS_TEMPLATES
+from gitignore_cli.templates import (
+    CREATED_LINE,
+    EDIT_LINE,
+    END_LINE,
+    SECTION_HEADER,
+    TemplateStore,
+)
+
+
+@dataclass
+class GitignoreFile:
+    path: Path
+    templates: list[str] = field(default_factory=list)
+    sections: dict[str, str] = field(default_factory=dict)
+    preamble: str = ""
+    managed: bool = False
+
+    @classmethod
+    def load(cls, path: Path, store: TemplateStore) -> GitignoreFile:
+        if not path.exists():
+            return cls(path=path)
+
+        content = path.read_text(encoding="utf-8")
+        parsed = cls(path=path)
+        created = CREATED_LINE.search(content)
+        edited = EDIT_LINE.search(content)
+        parsed.managed = bool(created or edited)
+
+        if created:
+            parsed.templates = [part.strip().lower() for part in created.group(1).split(",") if part.strip()]
+        elif edited:
+            parsed.templates = [part.strip().lower() for part in edited.group(1).split(",") if part.strip()]
+
+        end_match = END_LINE.search(content)
+        body = content[: end_match.start()] if end_match else content
+
+        if parsed.managed:
+            first_section = SECTION_HEADER.search(body)
+            parsed.preamble = body[: first_section.start()].strip() if first_section else body.strip()
+            for title, section in store.extract_sections(body):
+                template = store.title_to_template(title, candidates=parsed.templates)
+                key = template or title.lower()
+                parsed.sections[key] = section
+        else:
+            parsed.preamble = content.strip()
+
+        return parsed
+
+    def has_template(self, template: str) -> bool:
+        template = template.lower()
+        return template in self.templates or template in self.sections
+
+    def template_present(self, store: TemplateStore, template: str, content: str | None = None) -> bool:
+        template = template.lower()
+        if self.has_template(template):
+            return True
+        if content is None:
+            content = self.path.read_text(encoding="utf-8") if self.path.exists() else ""
+        if not content:
+            return False
+        title = store.section_title(template)
+        return f"### {title} ###" in content
+
+    def os_templates(self) -> list[str]:
+        return [template for template in self.templates if template in OS_TEMPLATES]
+
+    def language_templates(self) -> list[str]:
+        return [template for template in self.templates if template not in OS_TEMPLATES]
+
+    def render(self, store: TemplateStore, templates: list[str]) -> str:
+        ordered = store.sort_templates(templates)
+        if not ordered:
+            return ""
+
+        if not self.managed and self.preamble and not self.sections:
+            joined = ",".join(ordered)
+            appended = store.build_document(ordered)
+            return f"{self.preamble.rstrip()}\n\n{appended.rstrip()}\n"
+
+        joined = ",".join(ordered)
+        header = (
+            f"# Created by https://www.toptal.com/developers/gitignore/api/{joined}\n"
+            f"# Edit at https://www.toptal.com/developers/gitignore?templates={joined}\n"
+        )
+        sections: list[str] = []
+        for template in ordered:
+            if template in self.sections:
+                sections.append(self.sections[template].strip())
+            else:
+                sections.append(store.section_for_template(template).strip())
+
+        body = "\n\n".join(section for section in sections if section)
+        footer = f"# End of https://www.toptal.com/developers/gitignore/api/{joined}\n"
+        return f"{header}\n{body.rstrip()}\n\n{footer}"
+
+    def write(self, store: TemplateStore, templates: list[str]) -> None:
+        content = self.render(store, templates)
+        self.path.write_text(content, encoding="utf-8")
+
+    def add_template(self, store: TemplateStore, template: str) -> bool:
+        template = template.lower()
+        if self.has_template(template):
+            return False
+
+        self.templates.append(template)
+        self.sections[template] = store.section_for_template(template)
+        self.managed = True
+        return True
+
+    def append_templates(self, store: TemplateStore, templates: list[str]) -> list[str]:
+        """Append template sections without rewriting existing file content."""
+        content = self.path.read_text(encoding="utf-8") if self.path.exists() else ""
+        added: list[str] = []
+
+        for template in store.sort_templates(templates):
+            if self.template_present(store, template, content):
+                continue
+            section = store.section_for_template(template).strip()
+            if content and not content.endswith("\n"):
+                content += "\n"
+            if content.strip():
+                content += "\n"
+            content += section + "\n"
+            added.append(template)
+            if template not in self.templates:
+                self.templates.append(template)
+            self.sections[template] = section
+
+        if added:
+            self.path.write_text(content, encoding="utf-8")
+        return added

gitignore_cli/hooks.py

@@ -0,0 +1,182 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from gitignore_cli.deps import ensure_detection_tools
+from gitignore_cli.detect import detect_languages, detect_os_template
+from gitignore_cli.file import GitignoreFile
+from gitignore_cli.templates import get_store
+
+MARKER = "# Managed by gitignore-cli"
+TEMPLATE_DIR_NAME = "gitignore-cli"
+
+POST_CHECKOUT_HOOK = "post-checkout"
+PRE_PUSH_HOOK = "pre-push"
+
+INIT_BODY = """\
+# Create .gitignore when a repository is initialized (clone/checkout).
+root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+if [ ! -f "$root/.gitignore" ]; then
+  gi create --path "$root" 2>/dev/null || true
+fi
+"""
+
+SYNC_BODY = """\
+# Sync .gitignore before pushing (update if present, create if missing).
+root="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 0
+if [ -f "$root/.gitignore" ]; then
+  gi update --path "$root" 2>/dev/null || true
+else
+  gi create --path "$root" 2>/dev/null || true
+fi
+"""
+
+
+@dataclass(frozen=True)
+class HookSpec:
+    name: str
+    body: str
+    run_on_install: bool = False
+
+
+HOOKS = (
+    HookSpec(POST_CHECKOUT_HOOK, INIT_BODY, run_on_install=True),
+    HookSpec(PRE_PUSH_HOOK, SYNC_BODY),
+)
+
+
+def ensure_gitignore(repo_path: Path) -> bool:
+    """Create .gitignore when it is missing. Returns True if a file was created."""
+    gitignore_path = repo_path / ".gitignore"
+    if gitignore_path.exists():
+        return False
+
+    ensure_detection_tools()
+    store = get_store()
+    os_template = detect_os_template()
+    detected = detect_languages(repo_path, store)
+    templates = [os_template, *sorted(detected)]
+    document = GitignoreFile(path=gitignore_path)
+    document.write(store, store.sort_templates(templates))
+    return True
+
+
+def sync_gitignore(repo_path: Path) -> None:
+    """Update .gitignore when present, otherwise create it."""
+    gitignore_path = repo_path / ".gitignore"
+    if not gitignore_path.exists():
+        ensure_gitignore(repo_path)
+        return
+
+    ensure_detection_tools()
+    store = get_store()
+    os_template = detect_os_template()
+    document = GitignoreFile.load(gitignore_path, store)
+    detected = detect_languages(repo_path, store)
+    content = gitignore_path.read_text(encoding="utf-8")
+
+    to_add: list[str] = []
+    if not document.template_present(store, os_template, content):
+        to_add.append(os_template)
+    for template in sorted(detected):
+        if not document.template_present(store, template, content):
+            to_add.append(template)
+
+    document.append_templates(store, to_add)
+
+
+def find_git_dir(repo_path: Path) -> Path | None:
+    result = subprocess.run(
+        ["git", "-C", str(repo_path), "rev-parse", "--git-dir"],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        return None
+
+    git_dir = Path(result.stdout.strip())
+    if not git_dir.is_absolute():
+        git_dir = (repo_path / git_dir).resolve()
+    return git_dir
+
+
+def hooks_dir(repo_path: Path) -> Path | None:
+    git_dir = find_git_dir(repo_path)
+    if git_dir is None:
+        return None
+    return git_dir / "hooks"
+
+
+def global_template_dir() -> Path:
+    xdg_config = os.environ.get("XDG_CONFIG_HOME")
+    config_root = Path(xdg_config) if xdg_config else Path.home() / ".config"
+    return config_root / TEMPLATE_DIR_NAME / "template"
+
+
+def _render_hook(spec: HookSpec) -> str:
+    return f"#!/bin/sh\n{MARKER}\n{spec.body}"
+
+
+def _append_block(spec: HookSpec) -> str:
+    return f"\n# --- gitignore-cli: {spec.name} ---\n{MARKER}\n{spec.body}"
+
+
+def install_hook_file(path: Path, spec: HookSpec) -> str:
+    rendered = _render_hook(spec)
+    if not path.exists():
+        path.write_text(rendered, encoding="utf-8")
+        path.chmod(0o755)
+        return "installed"
+
+    existing = path.read_text(encoding="utf-8")
+    if MARKER in existing:
+        path.write_text(rendered, encoding="utf-8")
+        path.chmod(0o755)
+        return "updated"
+
+    path.write_text(existing.rstrip() + _append_block(spec) + "\n", encoding="utf-8")
+    path.chmod(0o755)
+    return "appended"
+
+
+def run_hook_body(spec: HookSpec, repo_path: Path) -> None:
+    if spec.name == POST_CHECKOUT_HOOK:
+        ensure_gitignore(repo_path)
+        return
+
+    sync_gitignore(repo_path)
+
+
+def install_repo_hooks(repo_path: Path) -> list[tuple[str, str]]:
+    target = hooks_dir(repo_path)
+    if target is None:
+        raise RuntimeError(f"{repo_path} is not inside a git repository.")
+
+    results: list[tuple[str, str]] = []
+    for spec in HOOKS:
+        status = install_hook_file(target / spec.name, spec)
+        results.append((spec.name, status))
+        if spec.run_on_install:
+            run_hook_body(spec, repo_path)
+    return results
+
+
+def install_global_template() -> Path:
+    template_root = global_template_dir()
+    hooks_target = template_root / "hooks"
+    hooks_target.mkdir(parents=True, exist_ok=True)
+
+    for spec in HOOKS:
+        path = hooks_target / spec.name
+        path.write_text(_render_hook(spec), encoding="utf-8")
+        path.chmod(0o755)
+
+    subprocess.run(
+        ["git", "config", "--global", "init.templateDir", str(template_root)],
+        check=True,
+    )
+    return template_root

gitignore_cli/ignored_dirs.py

@@ -0,0 +1,100 @@
+"""Directory names skipped during language detection.
+
+Any path component matching one of these names (case-insensitively) is not
+walked or scanned. Covers third-party dependencies, package caches, and common
+build output directories across languages and frameworks.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+# Stored lowercase; matched case-insensitively against each path component.
+IGNORED_DIRS = frozenset(
+    {
+        # Version control
+        ".git",
+        ".hg",
+        ".svn",
+        # Python
+        "__pycache__",
+        ".eggs",
+        ".hypothesis",
+        ".mypy_cache",
+        ".nox",
+        ".pytest_cache",
+        ".ruff_cache",
+        ".tox",
+        ".venv",
+        "env",
+        "site-packages",
+        "venv",
+        # JavaScript / Node / front-end package managers
+        ".pnp",
+        ".yarn",
+        "bower_components",
+        "jspm_packages",
+        "node_modules",
+        # PHP / Ruby / Composer / Bundler
+        ".bundle",
+        "vendor",
+        "vendors",
+        # Java / JVM / Android
+        ".gradle",
+        ".ivy2",
+        ".m2",
+        ".sbt",
+        "target",
+        # .NET / NuGet
+        ".nuget",
+        "packages",
+        # Go
+        "godeps",
+        # Rust / Cargo (target covered above)
+        # Elixir / Erlang / Phoenix
+        "_build",
+        "_checkouts",
+        "deps",
+        # Haskell / Stack
+        ".stack-work",
+        # Swift / iOS / CocoaPods / Carthage / Xcode
+        "carthage",
+        "deriveddata",
+        "deriveddatacache",
+        "pods",
+        # C / C++ / cross-language vendoring conventions
+        "3rdparty",
+        "dependencies",
+        "external",
+        "externals",
+        "third-party",
+        "third_party",
+        # Dart / Flutter
+        ".dart_tool",
+        ".pub-cache",
+        # Scala / Metals / Bloop
+        ".bloop",
+        ".metals",
+        # Zig
+        "zig-cache",
+        "zig-out",
+        # Unity / game engines (generated local package cache)
+        "library",
+        # Other dependency layouts
+        "_esy",
+        "_vendor",
+        "xvba_modules",
+        # Common build / distribution output
+        "build",
+        "dist",
+        "out",
+    }
+)
+
+
+def dir_name_is_ignored(name: str) -> bool:
+    return name.lower() in IGNORED_DIRS
+
+
+def path_is_ignored(path: Path | str) -> bool:
+    return any(dir_name_is_ignored(part) for part in Path(path).parts)

gitignore_cli/mapping.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import re
+
+# Linguist language names and magika labels mapped to gitignore.io template keys.
+LANGUAGE_ALIASES: dict[str, str] = {
+    "c#": "csharp",
+    "c++": "c++",
+    "clojure": "clojure",
+    "common lisp": "commonlisp",
+    "crystal": "crystal",
+    "css": "web",
+    "dart": "dart",
+    "elixir": "elixir",
+    "elm": "elm",
+    "erlang": "erlang",
+    "f#": "fsharp",
+    "fortran": "fortran",
+    "go": "go",
+    "groovy": "groovy",
+    "haskell": "haskell",
+    "html": "web",
+    "java": "java",
+    "javascript": "node",
+    "js": "node",
+    "jsonnet": "jsonnet",
+    "julia": "julia",
+    "kotlin": "kotlin",
+    "less": "less",
+    "lua": "lua",
+    "makefile": "cmake",
+    "nim": "nim",
+    "objective-c": "objective-c",
+    "ocaml": "ocaml",
+    "perl": "perl",
+    "php": "composer",
+    "powershell": "powershell",
+    "python": "python",
+    "r": "r",
+    "ruby": "ruby",
+    "rust": "rust",
+    "scala": "scala",
+    "scheme": "scheme",
+    "solidity": "solidity",
+    "sql": "database",
+    "svelte": "svelte",
+    "swift": "swift",
+    "typescript": "node",
+    "tsx": "node",
+    "tsxreact": "react",
+    "vue": "vue",
+    "zig": "zig",
+}
+
+OS_TEMPLATES = frozenset({"linux", "macos", "osx", "windows"})
+
+SKIP_MAGIKA_LABELS = frozenset(
+    {
+        "asm",
+        "batch",
+        "binary",
+        "csv",
+        "doc",
+        "docx",
+        "email",
+        "ignorefile",
+        "ini",
+        "json",
+        "markdown",
+        "pdf",
+        "pem",
+        "pptx",
+        "rtf",
+        "shell",
+        "svg",
+        "toml",
+        "txt",
+        "unknown",
+        "xlsx",
+        "xml",
+        "yaml",
+        "yml",
+    }
+)
+
+
+def normalize_key(value: str) -> str:
+    return re.sub(r"[^a-z0-9+]", "", value.lower())
+
+
+def resolve_template(name: str, available: set[str]) -> str | None:
+    lowered = name.lower().strip()
+    if lowered in available:
+        return lowered
+
+    alias = LANGUAGE_ALIASES.get(lowered)
+    if alias and alias in available:
+        return alias
+
+    normalized = normalize_key(lowered)
+    for candidate in available:
+        if normalize_key(candidate) == normalized:
+            return candidate
+
+    alias = LANGUAGE_ALIASES.get(normalized)
+    if alias and alias in available:
+        return alias
+
+    return None

gitignore_cli/templates.py

@@ -0,0 +1,163 @@
+from __future__ import annotations
+
+import json
+import re
+from functools import lru_cache
+from importlib.resources import files
+
+API_BASE = "https://www.toptal.com/developers/gitignore/api"
+CANONICAL_URL = "https://www.toptal.com/developers/gitignore"
+
+CREATED_LINE = re.compile(
+    r"^# Created by https://www\.toptal\.com/developers/gitignore/api/([^\s]+)\s*$",
+    re.MULTILINE,
+)
+EDIT_LINE = re.compile(
+    r"^# Edit at https://www\.toptal\.com/developers/gitignore\?templates=([^\s]+)\s*$",
+    re.MULTILINE,
+)
+SECTION_HEADER = re.compile(r"^### (.+?) ###\s*$", re.MULTILINE)
+END_LINE = re.compile(
+    r"^# End of https://www\.toptal\.com/developers/gitignore/api/[^\s]+\s*$",
+    re.MULTILINE,
+)
+
+_DATA_ROOT = files("gitignore_cli") / "data"
+
+
+class TemplateStore:
+    def __init__(self) -> None:
+        self._available: set[str] | None = None
+        self._order: dict[str, int] | None = None
+        self._section_titles: dict[str, str] = {}
+        self._template_cache: dict[str, str] = {}
+
+    @property
+    def available(self) -> set[str]:
+        if self._available is None:
+            self.refresh()
+        assert self._available is not None
+        return self._available
+
+    @property
+    def order(self) -> dict[str, int]:
+        if self._order is None:
+            self.refresh()
+        assert self._order is not None
+        return self._order
+
+    def refresh(self) -> None:
+        list_text = (_DATA_ROOT / "list.txt").read_text(encoding="utf-8")
+        self._available = {
+            line.strip().lower()
+            for line in list_text.splitlines()
+            if line.strip()
+        }
+
+        order_text = (_DATA_ROOT / "order.json").read_text(encoding="utf-8")
+        self._order = {key.lower(): value for key, value in json.loads(order_text).items()}
+
+    def _load_template(self, template: str) -> str:
+        template = template.lower()
+        if template not in self._template_cache:
+            path = _DATA_ROOT / "templates" / f"{template}.gitignore"
+            self._template_cache[template] = path.read_text(encoding="utf-8")
+        return self._template_cache[template]
+
+    def _strip_template_wrapper(self, content: str) -> str:
+        body = content
+        if CREATED_LINE.search(body):
+            body = CREATED_LINE.split(body, maxsplit=1)[-1]
+        body = EDIT_LINE.sub("", body, count=1)
+        if END_LINE.search(body):
+            body = END_LINE.split(body)[0]
+        return body.strip()
+
+    def fetch_templates(self, templates: list[str]) -> str:
+        if not templates:
+            return ""
+        ordered = self.sort_templates(list(set(templates)))
+        if len(ordered) == 1:
+            return self._load_template(ordered[0])
+
+        parts: list[str] = []
+        for template in ordered:
+            content = self._load_template(template)
+            sections = self.extract_sections(content)
+            if sections:
+                parts.append(sections[0][1].strip())
+            else:
+                parts.append(self._strip_template_wrapper(content))
+        return "\n\n".join(part for part in parts if part)
+
+    def section_title(self, template: str) -> str:
+        template = template.lower()
+        if template not in self._section_titles:
+            content = self.fetch_templates([template])
+            match = SECTION_HEADER.search(content)
+            self._section_titles[template] = match.group(1) if match else template
+        return self._section_titles[template]
+
+    def sort_templates(self, templates: list[str]) -> list[str]:
+        return sorted(set(templates), key=lambda name: (self.order.get(name, 9999), name))
+
+    def build_document(self, templates: list[str]) -> str:
+        ordered = self.sort_templates(templates)
+        if not ordered:
+            return ""
+        joined = ",".join(ordered)
+        body = self.fetch_templates(ordered)
+        if CREATED_LINE.search(body):
+            return body
+
+        sections = self.extract_sections(body)
+        content = "\n\n".join(section.strip() for _, section in sections if section.strip())
+        if not content:
+            content = body.strip()
+        return (
+            f"# Created by {API_BASE}/{joined}\n"
+            f"# Edit at {CANONICAL_URL}?templates={joined}\n\n"
+            f"{content.rstrip()}\n\n"
+            f"# End of {API_BASE}/{joined}\n"
+        )
+
+    def extract_sections(self, content: str) -> list[tuple[str, str]]:
+        sections: list[tuple[str, str]] = []
+        matches = list(SECTION_HEADER.finditer(content))
+        for index, match in enumerate(matches):
+            title = match.group(1)
+            start = match.start()
+            end = matches[index + 1].start() if index + 1 < len(matches) else len(content)
+            section_text = content[start:end].strip()
+            if END_LINE.search(section_text):
+                section_text = END_LINE.split(section_text)[0].strip()
+            sections.append((title, section_text))
+        return sections
+
+    def section_for_template(self, template: str) -> str:
+        content = self.fetch_templates([template])
+        sections = self.extract_sections(content)
+        if sections:
+            return sections[0][1]
+        return content.strip()
+
+    def title_to_template(self, title: str, candidates: list[str] | None = None) -> str | None:
+        normalized_title = re.sub(r"[^a-z0-9+]", "", title.lower())
+        search_set = [candidate.lower() for candidate in (candidates or [])]
+
+        for template in search_set:
+            if template not in self.available:
+                continue
+            if re.sub(r"[^a-z0-9+]", "", template) == normalized_title:
+                return template
+            section_title = re.sub(r"[^a-z0-9+]", "", self.section_title(template).lower())
+            if section_title == normalized_title:
+                return template
+        return None
+
+
+@lru_cache(maxsize=1)
+def get_store() -> TemplateStore:
+    store = TemplateStore()
+    store.refresh()
+    return store