Skip to content

Commit 9863a10

Browse files
cliffhallclaude
andcommitted
docs(git): document setting the commit identity via env vars or gitconfig
git_commit already takes the author and committer from GIT_AUTHOR_* and GIT_COMMITTER_* in the server's environment, then from user.name/user.email in Git config (GitPython's Actor). Document both routes in a new Commit identity section, add -e lines to the Docker examples, and pin each route with protocol-level tests. Closes #619 Co-Authored-By: Claude Opus 5.5 <[email protected]> Signed-off-by: cliffhall <[email protected]>
1 parent 446be48 commit 9863a10

2 files changed

Lines changed: 169 additions & 1 deletion

File tree

‎src/git/README.md‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,43 @@ python -m mcp_server_git
141141

142142
A tool call's `repo_path` must be inside that repository, and so must the directories Git then uses for it: a repository nested inside whose `.git` file, `commondir` or `core.worktree` points outside is refused. A linked worktree can still be the `--repository`, though its Git directory lives under the main repository's `.git`.
143143

144+
### Commit identity
145+
146+
`git_commit` has no identity setting of its own. It takes the author and the committer from the same places `git commit` does, in this order:
147+
148+
1. The server process's environment: `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` for the author, `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` for the committer. The author and the committer are resolved separately, so set all four (usually to the same name and email).
149+
2. `user.name` and `user.email` from Git config: the repository's `.git/config`, then `~/.gitconfig`, then `$XDG_CONFIG_HOME/git/config` (by default `~/.config/git/config`), then `/etc/gitconfig`.
150+
151+
Unlike `git commit`, the server does not refuse to commit when neither is set. It falls back to the operating-system user and host name, so a commit made in a container is recorded as something like `root <root@3f2a1b9c8d7e>`. A local install usually finds your own `~/.gitconfig`; a Docker container has none, so give it an identity explicitly.
152+
153+
For a local command (`uvx`, `python -m mcp_server_git`), add an `env` block to the server's entry in your client configuration:
154+
155+
```json
156+
"mcpServers": {
157+
"git": {
158+
"command": "uvx",
159+
"args": ["mcp-server-git", "--repository", "path/to/git/repo"],
160+
"env": {
161+
"GIT_AUTHOR_NAME": "Your Name",
162+
"GIT_AUTHOR_EMAIL": "[email protected]",
163+
"GIT_COMMITTER_NAME": "Your Name",
164+
"GIT_COMMITTER_EMAIL": "[email protected]"
165+
}
166+
}
167+
}
168+
```
169+
170+
For Docker, pass the variables to `docker run` with `-e`, as the Docker examples below do. Alternatively, mount your gitconfig read-only in place of the four `-e` pairs. The image runs as `root`, so it goes at `/root/.gitconfig`:
171+
172+
```json
173+
"args": [
174+
"run", "--rm", "-i",
175+
"--mount", "type=bind,src=/Users/username/.gitconfig,dst=/root/.gitconfig,readonly",
176+
"--mount", "type=bind,src=/Users/username,dst=/Users/username",
177+
"mcp/git"
178+
]
179+
```
180+
144181
### Usage with Claude Desktop
145182

146183
Add this to your `claude_desktop_config.json`:
@@ -162,12 +199,21 @@ Add this to your `claude_desktop_config.json`:
162199
<summary>Using docker</summary>
163200

164201
* Note: replace '/Users/username' with a path that you want to be accessible by this tool
202+
* Note: the `-e` lines set the identity `git_commit` records; see [Commit identity](#commit-identity)
165203

166204
```json
167205
"mcpServers": {
168206
"git": {
169207
"command": "docker",
170-
"args": ["run", "--rm", "-i", "--mount", "type=bind,src=/Users/username,dst=/Users/username", "mcp/git"]
208+
"args": [
209+
"run", "--rm", "-i",
210+
"-e", "GIT_AUTHOR_NAME=Your Name",
211+
212+
"-e", "GIT_COMMITTER_NAME=Your Name",
213+
214+
"--mount", "type=bind,src=/Users/username,dst=/Users/username",
215+
"mcp/git"
216+
]
171217
}
172218
}
173219
```
@@ -343,6 +389,10 @@ There are two ways to try your changes in a client:
343389
"run",
344390
"--rm",
345391
"-i",
392+
"-e", "GIT_AUTHOR_NAME=Your Name",
393+
394+
"-e", "GIT_COMMITTER_NAME=Your Name",
395+
346396
"--mount", "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
347397
"--mount", "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
348398
"--mount", "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",

‎src/git/tests/test_identity.py‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
"""Where `git_commit` takes the commit's author and committer from (#619).
2+
3+
The server sets no identity of its own: `git_commit` goes through GitPython's
4+
`IndexFile.commit`, whose `Actor` reads `GIT_AUTHOR_NAME`/`GIT_AUTHOR_EMAIL`
5+
and `GIT_COMMITTER_NAME`/`GIT_COMMITTER_EMAIL` from the server's environment
6+
first, then `user.name`/`user.email` from the repository's config, the user's
7+
`~/.gitconfig` and `$XDG_CONFIG_HOME/git/config`. The README's "Commit
8+
identity" section tells users to configure the server exactly that way (an
9+
`env` block, `docker run -e`, or a mounted gitconfig), so these tests pin each
10+
route through the protocol: a dependency upgrade or a refactor that stopped
11+
honoring one would otherwise silently commit as `root@<container id>`.
12+
"""
13+
14+
from pathlib import Path
15+
16+
import git
17+
import pytest
18+
19+
from conftest import connect, disable_autocrlf, text_result, wire
20+
21+
IDENTITY_VARS = (
22+
"GIT_AUTHOR_NAME",
23+
"GIT_AUTHOR_EMAIL",
24+
"GIT_COMMITTER_NAME",
25+
"GIT_COMMITTER_EMAIL",
26+
)
27+
28+
29+
@pytest.fixture(autouse=True)
30+
def clean_identity_env(monkeypatch: pytest.MonkeyPatch) -> None:
31+
"""Start every test with no identity in the environment, whatever CI sets."""
32+
for name in IDENTITY_VARS:
33+
monkeypatch.delenv(name, raising=False)
34+
35+
36+
async def commit_new_file(repo: git.Repo) -> git.Commit:
37+
"""Stage a new file, commit it through the protocol, return the commit."""
38+
assert repo.working_dir is not None
39+
root = Path(repo.working_dir)
40+
(root / "new.txt").write_text("new\n", newline="\n")
41+
repo.index.add(["new.txt"])
42+
async with connect(None) as session:
43+
result = wire(
44+
await session.call_tool(
45+
"git_commit", {"repo_path": str(root), "message": "add new"}
46+
)
47+
)
48+
head = repo.head.commit
49+
assert result == text_result(
50+
f"Changes committed successfully with hash {head.hexsha}"
51+
)
52+
return head
53+
54+
55+
async def test_environment_variables_set_author_and_committer(
56+
repo: git.Repo, monkeypatch: pytest.MonkeyPatch
57+
):
58+
# The `repo` fixture configures user.name/user.email repo-locally; the
59+
# environment wins over it, as it does for `git commit`.
60+
monkeypatch.setenv("GIT_AUTHOR_NAME", "Ada Author")
61+
monkeypatch.setenv("GIT_AUTHOR_EMAIL", "[email protected]")
62+
monkeypatch.setenv("GIT_COMMITTER_NAME", "Cy Committer")
63+
monkeypatch.setenv("GIT_COMMITTER_EMAIL", "[email protected]")
64+
65+
head = await commit_new_file(repo)
66+
67+
assert (head.author.name, head.author.email) == ("Ada Author", "[email protected]")
68+
assert (head.committer.name, head.committer.email) == (
69+
"Cy Committer",
70+
71+
)
72+
73+
74+
async def test_author_variables_alone_leave_the_committer_to_config(
75+
repo: git.Repo, monkeypatch: pytest.MonkeyPatch
76+
):
77+
# Author and committer are resolved separately, which is why the README
78+
# tells users to set all four variables.
79+
monkeypatch.setenv("GIT_AUTHOR_NAME", "Ada Author")
80+
monkeypatch.setenv("GIT_AUTHOR_EMAIL", "[email protected]")
81+
82+
head = await commit_new_file(repo)
83+
84+
assert (head.author.name, head.author.email) == ("Ada Author", "[email protected]")
85+
assert (head.committer.name, head.committer.email) == (
86+
"Test User",
87+
88+
)
89+
90+
91+
async def test_user_gitconfig_in_home_sets_the_identity(
92+
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
93+
):
94+
# The mounted-gitconfig route: no environment variables and no repo-local
95+
# identity, only a ~/.gitconfig under the server's HOME.
96+
home = tmp_path / "home"
97+
home.mkdir()
98+
(home / ".gitconfig").write_text(
99+
"[user]\n\tname = Gita Config\n\temail = [email protected]\n"
100+
)
101+
monkeypatch.setenv("HOME", str(home))
102+
monkeypatch.setenv("USERPROFILE", str(home)) # what expanduser reads on Windows
103+
monkeypatch.delenv("XDG_CONFIG_HOME", raising=False)
104+
105+
repo = git.Repo.init(tmp_path / "repo", initial_branch="main")
106+
try:
107+
disable_autocrlf(repo)
108+
head = await commit_new_file(repo)
109+
assert (head.author.name, head.author.email) == (
110+
"Gita Config",
111+
112+
)
113+
assert (head.committer.name, head.committer.email) == (
114+
"Gita Config",
115+
116+
)
117+
finally:
118+
repo.close()

0 commit comments

Comments
 (0)