gitlane 0.1.0__py3-none-any.whl

gitlane/__init__.py

@@ -0,0 +1,3 @@
+"""gitlane: a free, open-source Git client that runs in your browser."""
+
+__version__ = "0.1.0"

gitlane/__main__.py

@@ -0,0 +1,7 @@
+"""Allow ``python -m gitlane`` (used by the app-menu launcher)."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

gitlane/blobs.py

@@ -0,0 +1,77 @@
+"""Reading file contents at a given version, used for image previews."""
+
+from __future__ import annotations
+
+from pathlib import Path, PurePosixPath
+
+import git
+
+from .git_ops import GitError, check_paths
+from .graph import resolve_commit
+
+MAX_BLOB_BYTES = 20 * 1024 * 1024
+
+IMAGE_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".avif": "image/avif",
+    ".bmp": "image/bmp",
+    ".ico": "image/x-icon",
+    ".svg": "image/svg+xml",
+}
+
+# Special revisions besides commit ids.
+WORKTREE = "WORKTREE"  # the file on disk
+INDEX = "INDEX"  # the staged version
+HEAD = "HEAD"  # the last commit
+
+
+def image_type(path: str) -> str | None:
+    return IMAGE_TYPES.get(PurePosixPath(path).suffix.lower())
+
+
+def _spec(repo: git.Repo, rev: str, path: str) -> str:
+    if rev == INDEX:
+        return f":0:{path}"
+    if rev == HEAD:
+        return f"HEAD:{path}"
+    return f"{resolve_commit(repo, rev)}:{path}"
+
+
+def _worktree_file(repo: git.Repo, path: str) -> Path | None:
+    root = Path(repo.working_tree_dir).resolve()
+    f = (root / path).resolve()
+    if not f.is_relative_to(root) or not f.is_file():  # also blocks symlinks pointing outside
+        return None
+    return f
+
+
+def blob_exists(repo: git.Repo, rev: str, path: str) -> bool:
+    (path,) = check_paths([path])
+    if rev == WORKTREE:
+        return _worktree_file(repo, path) is not None
+    code, _, _ = repo.git.cat_file("-e", _spec(repo, rev, path),
+                                   with_extended_output=True, with_exceptions=False)
+    return code == 0
+
+
+def read_blob(repo: git.Repo, rev: str, path: str) -> bytes | None:
+    """Contents of ``path`` at ``rev``; None if the file does not exist there."""
+    (path,) = check_paths([path])
+    if rev == WORKTREE:
+        f = _worktree_file(repo, path)
+        if f is None:
+            return None
+        if f.stat().st_size > MAX_BLOB_BYTES:
+            raise GitError("File is too large to preview.")
+        return f.read_bytes()
+    spec = _spec(repo, rev, path)
+    code, size, _ = repo.git.cat_file("-s", spec, with_extended_output=True, with_exceptions=False)
+    if code != 0:
+        return None
+    if int(size) > MAX_BLOB_BYTES:
+        raise GitError("File is too large to preview.")
+    return repo.git.cat_file("blob", spec, stdout_as_string=False, strip_newline_in_stdout=False)

gitlane/branches.py

@@ -0,0 +1,267 @@
+"""Branch and commit operations (milestone 5).
+
+Every function returns a short message for the UI or raises GitError.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+import git
+
+from .git_ops import (GitError, _has_head, _network_kwargs, _run, check_paths, get_status,
+                      operation_in_progress)
+from .graph import resolve_commit
+
+RESET_MODES = ("soft", "mixed", "hard")
+
+
+@dataclass
+class Branch:
+    name: str
+    current: bool = False
+    upstream: str | None = None
+    ahead: int = 0
+    behind: int = 0
+    gone: bool = False  # upstream was deleted on the remote
+
+
+def list_branches(repo: git.Repo) -> tuple[list[Branch], list[str]]:
+    """Local branches and remote-tracking branch names (without */HEAD)."""
+    out = repo.git.for_each_ref(
+        "--format=%(refname)%00%(HEAD)%00%(upstream:short)%00%(upstream:track,nobracket)",
+        "refs/heads", "refs/remotes",
+    )
+    local, remote = [], []
+    for line in out.splitlines():
+        ref, head, upstream, track = (line.split("\0") + ["", "", ""])[:4]
+        if ref.startswith("refs/heads/"):
+            b = Branch(ref[len("refs/heads/"):], current=head == "*", upstream=upstream or None)
+            b.gone = track == "gone"
+            for m in re.finditer(r"(ahead|behind) (\d+)", track):
+                setattr(b, m.group(1), int(m.group(2)))
+            local.append(b)
+        elif ref.startswith("refs/remotes/") and not ref.endswith("/HEAD"):
+            remote.append(ref[len("refs/remotes/"):])
+    return local, remote
+
+
+def check_branch_name(repo: git.Repo, name: str) -> str:
+    name = (name or "").strip()
+    if not name:
+        raise GitError("Type a name for the branch.")
+    code, _, _ = repo.git.check_ref_format("--branch", name,
+                                           with_extended_output=True, with_exceptions=False)
+    if code != 0 or name.startswith("-"):
+        raise GitError(f"'{name}' is not a valid branch name.",
+                       hint="Branch names can't contain spaces, '..', '~', '^', ':', '?', '*', '[' "
+                            "or start with '-'. Try something like feature/login.")
+    return name
+
+
+def _local_names(repo: git.Repo) -> list[str]:
+    return [b.name for b in list_branches(repo)[0]]
+
+
+def _require_local(repo: git.Repo, name: str) -> str:
+    if name not in _local_names(repo):
+        raise GitError(f"Branch '{name}' not found.")
+    return name
+
+
+def _require_branch_or_remote(repo: git.Repo, name: str) -> str:
+    local, remote = list_branches(repo)
+    if name not in [b.name for b in local] and name not in remote:
+        raise GitError(f"Branch '{name}' not found.")
+    return name
+
+
+def _current_branch_name(repo: git.Repo) -> str | None:
+    return None if repo.head.is_detached else repo.active_branch.name
+
+
+def _no_operation(repo: git.Repo) -> None:
+    op = operation_in_progress(repo)
+    if op:
+        raise GitError(f"A {op} is in progress. Finish it or abort it first.")
+
+
+# --- branches ----------------------------------------------------------------
+
+def create_branch(repo: git.Repo, name: str, start: str | None = None, checkout: bool = True) -> str:
+    name = check_branch_name(repo, name)
+    if not _has_head(repo):
+        raise GitError("Make a first commit before creating branches.")
+    args = [resolve_commit(repo, start)] if start else []
+    if checkout:
+        _run(repo.git.switch, "-q", "-c", name, *args)
+        return f"Created branch {name} and switched to it."
+    _run(repo.git.branch, name, *args)
+    return f"Created branch {name}."
+
+
+def checkout(repo: git.Repo, name: str) -> str:
+    """Switch to a local branch, or to a remote branch (creating a local one)."""
+    _require_branch_or_remote(repo, name)
+    local_names = _local_names(repo)
+    if name in local_names:
+        _run(repo.git.switch, "-q", name)
+        return f"Switched to {name}."
+    # Remote branch like origin/feature -> local "feature" tracking it.
+    remotes = sorted((r.name for r in repo.remotes), key=len, reverse=True)
+    remote = next(r for r in remotes if name.startswith(r + "/"))
+    local = name[len(remote) + 1:]
+    if local in local_names:
+        _run(repo.git.switch, "-q", local)
+        return f"Switched to your existing local branch {local}."
+    _run(repo.git.switch, "-q", "-c", local, "--track", name)
+    return f"Created local branch {local} tracking {name} and switched to it."
+
+
+def checkout_commit(repo: git.Repo, sha: str) -> str:
+    sha = resolve_commit(repo, sha)
+    _run(repo.git.switch, "-q", "--detach", sha)
+    return f"Checked out {sha[:7]} (detached HEAD). Create a branch to keep new commits."
+
+
+def merge(repo: git.Repo, name: str) -> str:
+    _require_branch_or_remote(repo, name)
+    current = _current_branch_name(repo)
+    if current is None:
+        raise GitError("You are not on a branch (detached HEAD). Switch to a branch first.")
+    if name == current:
+        raise GitError("A branch can't be merged into itself.")
+    _no_operation(repo)
+    before = repo.head.commit.hexsha
+    _run(repo.git.merge, "--no-edit", name)
+    if repo.head.commit.hexsha == before:
+        return f"{current} already contains everything in {name}."
+    return f"Merged {name} into {current}."
+
+
+def delete_branch(repo: git.Repo, name: str, force: bool = False) -> str:
+    _require_local(repo, name)
+    if name == _current_branch_name(repo):
+        raise GitError(f"You can't delete {name} because it is the current branch. "
+                       "Switch to another branch first.")
+    try:
+        _run(repo.git.branch, "-D" if force else "-d", name)
+    except GitError as e:
+        if "not fully merged" in str(e):
+            e.action = {
+                "label": "Delete anyway", "url": "/actions/branch/delete",
+                "vals": {"name": name, "force": "1"},
+                "confirm": f"Delete {name} anyway?\n\nIts unmerged commits will no longer be on any "
+                           "branch and may be lost.",
+            }
+        raise
+    return f"Deleted branch {name}."
+
+
+def _split_remote(repo: git.Repo, name: str) -> tuple[str, str]:
+    """"origin/feature/x" -> ("origin", "feature/x"), using the real remote names."""
+    remotes = sorted((r.name for r in repo.remotes), key=len, reverse=True)
+    remote = next((r for r in remotes if name.startswith(r + "/")), None)
+    if remote is None:
+        raise GitError(f"Remote branch '{name}' not found.")
+    return remote, name[len(remote) + 1:]
+
+
+def delete_remote_branch(repo: git.Repo, name: str) -> str:
+    """Delete a branch on the remote server (``git push <remote> --delete <branch>``)."""
+    if name not in list_branches(repo)[1]:
+        raise GitError(f"Remote branch '{name}' not found.")
+    remote, branch = _split_remote(repo, name)
+    code, default, _ = repo.git.symbolic_ref("--short", "-q", f"refs/remotes/{remote}/HEAD",
+                                            with_extended_output=True, with_exceptions=False)
+    if code == 0 and default.strip() == name:
+        raise GitError(f"{branch} is the default branch of {remote}, so it can't be deleted here.",
+                       hint="Pick another default branch in the repository settings on GitHub "
+                            "(or your Git host) first.")
+    try:
+        _run(repo.git.push, remote, "--delete", branch, **_network_kwargs(repo))
+    except GitError as e:
+        if "remote ref does not exist" not in str(e):
+            raise
+        # Someone already deleted it on the server: just drop our stale copy.
+        _run(repo.git.branch, "-r", "-d", name)
+        return f"{branch} was already gone from {remote}; removed the old copy of {name}."
+    kept = [b.name for b in list_branches(repo)[0] if b.upstream == name]
+    note = f" Your local branch {kept[0]} is kept." if kept else ""
+    return f"Deleted {branch} on {remote}.{note}"
+
+
+# --- commit operations ---------------------------------------------------------
+
+def _single_parent(repo: git.Repo, sha: str, what: str) -> str:
+    sha = resolve_commit(repo, sha)
+    if len(repo.commit(sha).parents) > 1:
+        raise GitError(f"{what} merge commits isn't supported yet. Use a terminal for this one.")
+    return sha
+
+
+def cherry_pick(repo: git.Repo, sha: str) -> str:
+    _no_operation(repo)
+    sha = _single_parent(repo, sha, "Cherry-picking")
+    _run(repo.git.cherry_pick, sha)
+    return f"Cherry-picked {sha[:7]} onto {_current_branch_name(repo) or 'HEAD'}."
+
+
+def revert(repo: git.Repo, sha: str) -> str:
+    _no_operation(repo)
+    sha = _single_parent(repo, sha, "Reverting")
+    _run(repo.git.revert, "--no-edit", sha)
+    return f"Reverted {sha[:7]} with a new commit."
+
+
+def reset(repo: git.Repo, sha: str, mode: str) -> str:
+    if mode not in RESET_MODES:
+        raise GitError("Unknown reset mode.")
+    _no_operation(repo)
+    sha = resolve_commit(repo, sha)
+    _run(repo.git.reset, "-q", f"--{mode}", sha)
+    where = _current_branch_name(repo) or "HEAD"
+    return f"Reset {where} to {sha[:7]} ({mode})."
+
+
+# --- merge conflicts ------------------------------------------------------------
+
+_MARKER = re.compile(rb"^(<{7} |>{7} |={7}$)", re.MULTILINE)
+
+
+def abort_operation(repo: git.Repo) -> str:
+    op = operation_in_progress(repo)
+    if op is None:
+        raise GitError("There is nothing to abort.")
+    _run(getattr(repo.git, op.replace("-", "_")), "--abort")
+    return f"{op.capitalize()} aborted. Everything is back to how it was before."
+
+
+def continue_operation(repo: git.Repo) -> str:
+    """Stage the conflicted files and finish the merge / cherry-pick / revert."""
+    op = operation_in_progress(repo)
+    if op is None:
+        raise GitError("There is nothing to continue.")
+    if op == "rebase":
+        raise GitError("Finishing a rebase isn't supported yet. Use `git rebase --continue` "
+                       "in a terminal, or abort it here.")
+    conflicted = [f.path for f in get_status(repo).conflicted]
+    root = Path(repo.working_tree_dir)
+    still = [p for p in check_paths(conflicted) if (root / p).is_file()
+             and _MARKER.search((root / p).read_bytes())] if conflicted else []
+    if still:
+        raise GitError(
+            "These files still contain conflict markers (<<<<<<<, =======, >>>>>>>): "
+            + ", ".join(still),
+            hint="Open them in your editor, keep the right lines, delete the markers, save, "
+                 "then try again.",
+        )
+    if conflicted:
+        _run(repo.git.add, "--all", "--", *conflicted)
+    if op == "merge":
+        _run(repo.git.commit, "--no-edit", "-q")
+    else:
+        _run(getattr(repo.git, op.replace("-", "_")), "--continue")
+    return f"{op.capitalize()} completed."

gitlane/cli.py

@@ -0,0 +1,130 @@
+"""The ``gitlane`` command: start the local server and open the browser.
+
+``gitlane <path>`` opens that repo as a tab (next to the remembered tabs).
+Plain ``gitlane`` opens the repo in the current folder, or, outside a repo,
+the page where you pick one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import secrets
+import shutil
+import socket
+import subprocess
+import sys
+import threading
+import time
+import webbrowser
+from pathlib import Path
+
+from . import __version__
+
+HOST = "127.0.0.1"  # never 0.0.0.0 (SPEC.md §3)
+MIN_GIT = (2, 23)  # first version with `git switch` and `git restore`
+
+
+def check_git() -> str | None:
+    """Return a readable problem if Git is missing or too old, else None.
+
+    Runs before GitPython is imported: GitPython fails at import time with
+    a cryptic message when there is no ``git`` program.
+    """
+    exe = shutil.which("git")
+    if exe is None:
+        return ("Git is not installed (or not on your PATH). Install it from "
+                "https://git-scm.com/downloads and try again.")
+    try:
+        out = subprocess.run([exe, "--version"], capture_output=True, text=True, timeout=10).stdout
+    except (OSError, subprocess.SubprocessError):
+        return f"Could not run {exe}. Check that Git works in a terminal: git --version"
+    m = re.search(r"(\d+)\.(\d+)", out)
+    if m and (int(m[1]), int(m[2])) < MIN_GIT:
+        need = ".".join(map(str, MIN_GIT))
+        return f"Your Git is too old ({out.strip()}). gitlane needs Git {need} or newer."
+    return None
+
+
+def find_free_port() -> int:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.bind((HOST, 0))
+        return s.getsockname()[1]
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    p = argparse.ArgumentParser(prog="gitlane", description="Open a Git repository in your browser.")
+    p.add_argument("path", nargs="?", default=None,
+                   help="folder inside a repository (default: the current folder, if it is one)")
+    p.add_argument("--port", type=int, default=None, help="port to listen on (default: a free port)")
+    p.add_argument("--no-browser", action="store_true", help="do not open the browser automatically")
+    p.add_argument("--install-launcher", action="store_true",
+                   help="add gitlane to your app menu (Linux), then exit")
+    p.add_argument("--remove-launcher", action="store_true",
+                   help="remove gitlane from your app menu (Linux), then exit")
+    p.add_argument("--version", action="version", version=f"gitlane {__version__}")
+    return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = parse_args(argv)
+    if args.install_launcher or args.remove_launcher:
+        from . import launcher
+
+        try:
+            msg = launcher.install() if args.install_launcher else launcher.remove()
+        except launcher.LauncherError as e:
+            print(f"gitlane: {e}", file=sys.stderr)
+            return 1
+        print(msg)
+        return 0
+
+    problem = check_git()
+    if problem:
+        print(f"gitlane: {problem}", file=sys.stderr)
+        return 1
+
+    from .git_ops import NotAGitRepo, open_repo
+
+    try:
+        repo = open_repo(args.path or ".")
+    except NotAGitRepo as e:
+        if args.path is not None:  # asked for a specific folder: say what's wrong
+            print(f"gitlane: {e}", file=sys.stderr)
+            print("Pass a folder inside a Git repository, e.g. gitlane ~/dev/myproject, "
+                  "or run plain gitlane and pick one in the browser.", file=sys.stderr)
+            return 1
+        repo_root = None  # pick a repo in the browser
+    else:
+        repo_root = Path(repo.working_tree_dir)
+        repo.close()
+
+    import uvicorn  # imported late so `gitlane --help` stays fast
+
+    from .server import create_app
+
+    port = args.port or find_free_port()
+    token = secrets.token_urlsafe(32)
+    url = f"http://{HOST}:{port}/?token={token}"
+
+    app = create_app(repo_root, token, port)
+    server = uvicorn.Server(uvicorn.Config(app, host=HOST, port=port, log_level="warning"))
+
+    def announce() -> None:
+        while not server.started and not server.should_exit:
+            time.sleep(0.05)
+        if server.should_exit:
+            return
+        print(f"gitlane {__version__} — {repo_root or 'pick a repository in the browser'}", flush=True)
+        print(f"Open: {url}", flush=True)
+        print("Press Ctrl+C to stop.", flush=True)
+        if not args.no_browser:
+            webbrowser.open(url)
+
+    threading.Thread(target=announce, daemon=True).start()
+    server.run()
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())