From ceeae9b5e2625e23e6e3792d06a6c8122a36d18b Mon Sep 17 00:00:00 2001
From: Craig Jennings <c@cjennings.net>
Date: Sat, 16 May 2026 04:26:20 -0500
Subject: feat(gptel-tools): wire git_status / git_log / git_diff as local
 tools
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Three read-only git context tools so gptel can see what's changed
without me pasting `git status` / `git log` / `git diff` output into
every chat turn.  Builds the first batch from the ADOPT bucket in
`docs/design/gptel-tools-shortlist.org`.

Shape per tool:

- `gptel-tools/git_status.el` — `git status --short --branch` for a
  directory inside a git working tree under HOME.  Returns the
  porcelain output, or a "Clean working tree" marker when only the
  branch line is present.
- `gptel-tools/git_log.el` — `git log --oneline -nN` with an optional
  `--since` filter.  N defaults to 20, capped at 100; nil / non-
  integer / out-of-range N falls back to the default.
- `gptel-tools/git_diff.el` — `git diff [REF1 [REF2]] [-- FILE]`.
  Output capped at ~500KB so a runaway diff can't blow up context;
  truncation is reported inline.

Validation is uniform: path must resolve under HOME, must be a
directory, must be inside a git working tree (verified via
`git rev-parse --is-inside-work-tree`).  Color is disabled via
`-c color.ui=false` at the git level (`git status` doesn't accept
`--no-color` directly).

Tests run against real temp git repos created via `process-file`,
not mocked — there's nothing in gptel-tools/git_*.el that's
process-mockable in a meaningful way, and a real `git init` + a
couple of commits is cheaper than building a fake.  31 tests total:
7 for git_status, 11 for git_log, 13 for git_diff.

Wired into `cj/gptel-local-tool-features` so gptel exposes the
three tools on next restart.
---
 gptel-tools/git_status.el | 79 +++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 gptel-tools/git_status.el

(limited to 'gptel-tools/git_status.el')

diff --git a/gptel-tools/git_status.el b/gptel-tools/git_status.el
new file mode 100644
index 00000000..300d5da5
--- /dev/null
+++ b/gptel-tools/git_status.el
@@ -0,0 +1,79 @@
+;;; git_status.el --- Read-only git status tool for gptel -*- coding: utf-8; lexical-binding: t; -*-
+
+;; Author: Craig Jennings <c@cjennings.net>
+;; Keywords: convenience, tools, git
+
+;; This file is not part of GNU Emacs.
+
+;;; Commentary:
+
+;; Gptel tool returning `git status --short --branch' for a path under
+;; the user's home directory.  Read-only: never writes to the repo,
+;; never runs anything that could mutate state.  Path validation
+;; rejects anything outside HOME and any path that doesn't resolve to
+;; a directory inside a git working tree.
+
+;;; Code:
+
+(require 'gptel)
+(require 'cl-lib)
+
+(defun cj/gptel-git-status--validate-path (path)
+  "Validate PATH as a usable working directory for a git status call.
+PATH must resolve under the user's home directory, must be an
+existing directory, and must be inside a git working tree.  Returns
+the expanded path string on success; signals `error' otherwise."
+  (let ((full (expand-file-name (or path "~") "~")))
+    (unless (string-prefix-p (expand-file-name "~") full)
+      (error "Path must be within home directory: %s" path))
+    (unless (file-directory-p full)
+      (error "Not a directory: %s" full))
+    (let ((default-directory full))
+      (unless (zerop (process-file "git" nil nil nil
+                                   "rev-parse" "--is-inside-work-tree"))
+        (error "Not a git working tree: %s" full)))
+    full))
+
+(defun cj/gptel-git-status--run (path)
+  "Run `git status --short --branch' in PATH.  Return the output.
+Color is disabled via `-c color.ui=false' at the git level (`git status'
+itself doesn't accept `--no-color' like `git log' / `git diff' do)."
+  (let* ((dir (cj/gptel-git-status--validate-path path))
+         (default-directory dir))
+    (with-temp-buffer
+      (let ((exit (process-file "git" nil t nil
+                                "-c" "color.ui=false"
+                                "status" "--short" "--branch")))
+        (unless (zerop exit)
+          (error "git status exited with %d: %s" exit (buffer-string)))
+        ;; `--branch' always prints a `## <branch>' header, so empty
+        ;; output is unreachable.  Detect a clean tree by counting the
+        ;; non-branch lines: if only the header is present, no files
+        ;; are modified / staged / untracked.
+        (let* ((out (buffer-string))
+               (non-branch-lines
+                (cl-count-if
+                 (lambda (l)
+                   (and (not (string-empty-p l))
+                        (not (string-prefix-p "## " l))))
+                 (split-string out "\n"))))
+          (if (zerop non-branch-lines)
+              (format "Clean working tree in %s\n%s" dir (string-trim out))
+            out))))))
+
+(with-eval-after-load 'gptel
+  (gptel-make-tool
+   :name "git_status"
+   :function (lambda (path) (cj/gptel-git-status--run path))
+   :description "Return the output of `git status --short --branch' for a directory in the user's home tree.  Read-only.  Useful for seeing which files are modified, staged, or untracked, and how the current branch compares to its upstream."
+   :args (list '(:name "path"
+                       :type string
+                       :description "Directory inside a git working tree.  Either an absolute path under the user's home directory or a path relative to it (e.g. 'code/myproject')."))
+   :category "git"
+   :confirm nil
+   :include t)
+
+  (add-to-list 'gptel-tools (gptel-get-tool '("git" "git_status"))))
+
+(provide 'git_status)
+;;; git_status.el ends here
-- 
cgit v1.2.3