gitwhy-context-saving

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GitWhy — Context Layer for Git

GitWhy — Git的上下文层

Save, retrieve, and share the reasoning behind AI-generated code — tied to commits.

Workflows: See WORKFLOWS.md for when/how to save, retrieve, and push. Troubleshooting: See TROUBLESHOOTING.md for common errors and diagnostics.

保存、检索并分享与提交记录关联的AI生成代码背后的推理过程。

工作流：有关保存、检索和推送的时机与方法，请查看WORKFLOWS.md。 故障排查：有关常见错误与诊断方法，请查看TROUBLESHOOTING.md。

Two Ways to Use GitWhy

GitWhy的两种使用方式

GitWhy works via MCP tools (if available) or CLI commands (always available). Both are equivalent — use whichever works in your environment.

MCP Tool	CLI Command	Purpose
`gitwhy_status`	`git why log`	Check saved contexts and pending commits
`gitwhy_save`	`git why save --file context.md`	Save structured context
`gitwhy_get`	`git why get <id>`	Retrieve context by ID
`gitwhy_search`	`git why search "<query>"`	Search contexts by keyword
`gitwhy_list`	`git why tree` / `git why log`	Browse domain/topic structure
`gitwhy_sync`	`git why push`	Upload to cloud (private)
`gitwhy_publish`	`git why push --share`	Share with team
`gitwhy_post_pr`	`git why post-pr`	Post to GitHub PR

MCP fallback rule: If an MCP tool fails or is unavailable, inform the user and use the equivalent CLI command instead. Every MCP operation has a CLI equivalent.

GitWhy可通过MCP工具（若可用）或CLI命令（始终可用）运行。两者功能等效，可根据你的环境选择使用。

MCP 工具	CLI 命令	用途
`gitwhy_status`	`git why log`	查看已保存的上下文和待提交记录
`gitwhy_save`	`git why save --file context.md`	保存结构化上下文
`gitwhy_get`	`git why get <id>`	通过ID检索上下文
`gitwhy_search`	`git why search "<query>"`	通过关键词搜索上下文
`gitwhy_list`	`git why tree` / `git why log`	浏览领域/主题结构
`gitwhy_sync`	`git why push`	上传至云端（私有）
`gitwhy_publish`	`git why push --share`	与团队共享
`gitwhy_post_pr`	`git why post-pr`	发布至GitHub PR

MCP降级规则：若MCP工具运行失败或不可用，请告知用户并使用等效的CLI命令替代。所有MCP操作都有对应的CLI命令。

Context Format (XML Input)

上下文格式（XML输入）

When saving context, wrap content in

<context>

XML tags. The CLI renders this into rich markdown for storage.

xml

<context>
  <!-- Required -->
  <title>Short title of what was done</title>
  <story>
    Organize by phases. Write in first-person engineering journal style.

    Phase 1 — Setup:
    What user asked, what you did, challenges faced, how you resolved them.
    Include back-and-forth with the user where it shaped the outcome.

    Phase 2 — Implementation:
    Technical details, decisions made during coding, problems solved.
  </story>
  <reasoning>
    Why you chose this approach.

    <decisions>
      - RS256 over HS256 — allows key rotation without redeploying
      - 24h token expiry — balances security vs UX
    </decisions>

    <rejected>
      - Session cookies — requires server-side session store
      - OAuth2 external provider — overkill for internal service
    </rejected>

    <tradeoffs>
      - No refresh tokens in v1 — simplifies MVP but means 24h hard limit
    </tradeoffs>
  </reasoning>
  <files>
    src/auth/middleware.ts — new — Token verification middleware
    src/routes/login.ts — modified — Added token signing on login
    package.json — modified — Added jsonwebtoken dependency
  </files>

  <!-- Optional -->
  <agent>claude-code (claude-opus-4)</agent>
  <tags>auth, jwt, middleware</tags>
  <tools>MCP: nia, sequential-thinking</tools>
  <verification>All 14 tests passing. Build successful.</verification>
  <risks>No rate limiting on login endpoint yet.</risks>
</context>

保存上下文时，请将内容包裹在

<context>

XML标签中。CLI会将其渲染为富文本Markdown格式进行存储。

xml

<context>
  <!-- Required -->
  <title>Short title of what was done</title>
  <story>
    Organize by phases. Write in first-person engineering journal style.

    Phase 1 — Setup:
    What user asked, what you did, challenges faced, how you resolved them.
    Include back-and-forth with the user where it shaped the outcome.

    Phase 2 — Implementation:
    Technical details, decisions made during coding, problems solved.
  </story>
  <reasoning>
    Why you chose this approach.

    <decisions>
      - RS256 over HS256 — allows key rotation without redeploying
      - 24h token expiry — balances security vs UX
    </decisions>

    <rejected>
      - Session cookies — requires server-side session store
      - OAuth2 external provider — overkill for internal service
    </rejected>

    <tradeoffs>
      - No refresh tokens in v1 — simplifies MVP but means 24h hard limit
    </tradeoffs>
  </reasoning>
  <files>
    src/auth/middleware.ts — new — Token verification middleware
    src/routes/login.ts — modified — Added token signing on login
    package.json — modified — Added jsonwebtoken dependency
  </files>

  <!-- Optional -->
  <agent>claude-code (claude-opus-4)</agent>
  <tags>auth, jwt, middleware</tags>
  <tools>MCP: nia, sequential-thinking</tools>
  <verification>All 14 tests passing. Build successful.</verification>
  <risks>No rate limiting on login endpoint yet.</risks>
</context>

Tag Requirements

标签要求

Tag	Required	Notes
`<title>`	Yes	Short title of the work done
`<story>`	Yes	Phase-organized engineering journal. First-person, chronological.
`<reasoning>`	Yes	Why this approach. Nest `<decisions>` , `<rejected>` , `<tradeoffs>` inside.
`<files>`	Yes	One per line. Flexible format: `path — status — desc` or just `path`
`<agent>`	Optional	Agent name and model
`<tags>`	Optional	Comma-separated keywords for discovery
`<tools>`	Optional	MCPs, CLI tools, resources used
`<verification>`	Optional	Test results, build status
`<risks>`	Optional	Open questions, follow-up items

Context ID, repository, branch, date, domain/topic, and commits are auto-populated by the CLI.

标签	是否必填	说明
`<title>`	是	工作内容的简短标题
`<story>`	是	按阶段组织的工程日志，采用第一人称、按时间顺序撰写
`<reasoning>`	是	选择此方案的原因。需在内部嵌套 `<decisions>` 、 `<rejected>` 、 `<tradeoffs>` 标签
`<files>`	是	每行一个文件。格式灵活： `路径 — 状态 — 描述` 或仅填写 `路径`
`<agent>`	可选	Agent名称及模型
`<tags>`	可选	用于检索的逗号分隔关键词
`<tools>`	可选	使用的MCP、CLI工具及资源
`<verification>`	可选	测试结果、构建状态
`<risks>`	可选	待解决问题、后续跟进事项

上下文ID、仓库、分支、日期、领域/主题及提交记录由CLI自动填充。

Quick Start

快速开始

Check status:
```
gitwhy_status
```
(MCP) or
```
git why log
```
(CLI)
Developer says: "Save this session with GitWhy"
You generate context in
```
<context>
```
XML tags using the template above

Save context:

MCP: Call

gitwhy_save(markdown="<context>...</context>")

CLI: Write content to file, then run
```
git why save --file context.md
```

CLI (pipe):

echo '<context>...</context>' | git why save

GitWhy parses XML, renders rich markdown, generates context ID, stores locally
Context ID is returned — use it for retrieval later

To retrieve past context:

By ID:

gitwhy_get(id="ctx_a1b2c3d4")

git why get ctx_a1b2c3d4

By search:

gitwhy_search(query="authentication")

git why search "auth"

Browse tree:
```
gitwhy_list()
```
or
```
git why tree
```

To share with team:

Sync to cloud:
```
gitwhy_sync
```
or
```
git why push
```

Publish:

gitwhy_publish(ids=...)

git why push --share

Post to PR:
```
gitwhy_post_pr
```
or
```
git why post-pr
```

查看状态：
```
gitwhy_status
```
（MCP工具）或
```
git why log
```
（CLI命令）
开发者提出：“用GitWhy保存本次会话”
使用上述模板在
```
<context>
```
XML标签中生成上下文

保存上下文：

MCP工具： 调用

gitwhy_save(markdown="<context>...</context>")

CLI命令： 将内容写入文件，然后运行
```
git why save --file context.md
```

CLI（管道方式）：

echo '<context>...</context>' | git why save

GitWhy解析XML，渲染为富文本Markdown，生成上下文ID并本地存储
返回上下文ID — 后续可使用该ID检索上下文

检索过往上下文：

通过ID：

gitwhy_get(id="ctx_a1b2c3d4")

或

git why get ctx_a1b2c3d4

通过搜索：

gitwhy_search(query="authentication")

或

git why search "auth"

浏览树形结构：
```
gitwhy_list()
```
或
```
git why tree
```

与团队共享：

同步至云端：
```
gitwhy_sync
```
或
```
git why push
```

发布：

gitwhy_publish(ids=...)

或

git why push --share

发布至PR：
```
gitwhy_post_pr
```
或
```
git why post-pr
```