git-structured

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Git Structured Skill

Perform safe, structured Git operations with JSON output. Provides read-only and write operations with safety checks.

执行带有JSON输出的安全、结构化Git操作。提供带有安全检查的只读和写入操作。

When to Use

适用场景

✅ USE this skill when:

Checking repository status
Making commits
Managing branches
Viewing history and diffs
Stash operations

❌ DON'T use this skill when:

Destructive operations without backup
Force pushing to protected branches
Rewriting history on shared branches

✅ 推荐使用本Skill的场景：

检查仓库状态
提交代码
分支管理
查看历史记录与差异
暂存操作

❌ 不推荐使用本Skill的场景：

无备份的破坏性操作
强制推送到受保护分支
在共享分支上重写历史记录

Usage

使用方法

Status

状态查询

javascript

const { git } = require('/job/.pi/skills/git-structured/git.js');

const status = await git('status');
console.log(status);
// {
//   branch: "main",
//   staged: [{ path: "src/index.js", status: "M" }],
//   unstaged: [],
//   untracked: ["new-file.md"],
//   clean: false
// }

javascript

const { git } = require('/job/.pi/skills/git-structured/git.js');

const status = await git('status');
console.log(status);
// {
//   branch: "main",
//   staged: [{ path: "src/index.js", status: "M" }],
//   unstaged: [],
//   untracked: ["new-file.md"],
//   clean: false
// }

Diff

差异对比

javascript

const diff = await git('diff', {
  cached: false,
  files: "src/"
});
console.log(diff);
// {
//   files: [{
//     path: "src/index.js",
//     hunks: [
//       { start: 10, lines: "+ console.log('new');" }
//     ]
//   }]
// }

javascript

const diff = await git('diff', {
  cached: false,
  files: "src/"
});
console.log(diff);
// {
//   files: [{
//     path: "src/index.js",
//     hunks: [
//       { start: 10, lines: "+ console.log('new');" }
//     ]
//   }]
// }

Log

提交日志

javascript

const log = await git('log', {
  maxEntries: 10,
  format: "short"
});
console.log(log);
// [
//   { hash: "abc123", author: "John", date: "2026-02-25", message: "Fix bug" },
//   ...
// ]

javascript

const log = await git('log', {
  maxEntries: 10,
  format: "short"
});
console.log(log);
// [
//   { hash: "abc123", author: "John", date: "2026-02-25", message: "Fix bug" },
//   ...
// ]

Add & Commit

添加与提交

javascript

await git('add', { files: ["src/index.js", "src/utils.js"] });

const commit = await git('commit', {
  message: "Add new feature",
  all: false // use -a flag
});
console.log(commit);
// { hash: "def456", changedFiles: 2 }

javascript

await git('add', { files: ["src/index.js", "src/utils.js"] });

const commit = await git('commit', {
  message: "Add new feature",
  all: false // use -a flag
});
console.log(commit);
// { hash: "def456", changedFiles: 2 }

Branch

分支管理

javascript

// List branches
const branches = await git('branch');
// { current: "main", branches: ["main", "feature", "bugfix"] }

// Create branch
await git('checkout', {  
  newBranch: "feature/new-ui",
  startPoint: "main"
});

// Switch branch
await git('checkout', { branch: "main" });

javascript

// 列出分支
const branches = await git('branch');
// { current: "main", branches: ["main", "feature", "bugfix"] }

// 创建分支
await git('checkout', {  
  newBranch: "feature/new-ui",
  startPoint: "main"
});

// 切换分支
await git('checkout', { branch: "main" });

Push & Pull

推送与拉取

javascript

const push = await git('push', {
  remote: "origin",
  branch: "feature",
  setUpstream: true
});

const pull = await git('pull', {
  remote: "origin",
  rebase: false
});

javascript

const push = await git('push', {
  remote: "origin",
  branch: "feature",
  setUpstream: true
});

const pull = await git('pull', {
  remote: "origin",
  rebase: false
});

Stash

暂存操作

javascript

await git('stash', { action: 'push', message: 'WIP' });
await git('stash', { action: 'list' });
await git('stash', { action: 'pop', index: 0 });

javascript

await git('stash', { action: 'push', message: 'WIP' });
await git('stash', { action: 'list' });
await git('stash', { action: 'pop', index: 0 });

API

javascript

git(operation, options = {})

Operations:

status

diff

log

add

commit

branch

checkout

push

pull

stash

reset

revert

Options vary by operation:

javascript

// Diff options
{ cached: true, files: "src/" }

// Commit options  
{ message: "msg", all: true, amend: false }

// Checkout options
{ branch: "main" } or { newBranch: "feature", startPoint: "main" }

javascript

git(operation, options = {})

支持的操作：

status

diff

log

add

commit

branch

checkout

push

pull

stash

reset

revert

操作选项因操作类型而异：

javascript

// 差异对比选项
{ cached: true, files: "src/" }

// 提交选项  
{ message: "msg", all: true, amend: false }

// 切换分支选项
{ branch: "main" } 或 { newBranch: "feature", startPoint: "main" }

Safety Features

安全特性

Injection Prevention

注入防护

Argument sanitization
No shell expansion
Blocked dangerous flags (
```
--exec=
```
,
```
--upload-pack=
```
)

参数校验
无Shell扩展
拦截危险标志（
```
--exec=
```
,
```
--upload-pack=
```
）

Write Access Control

写入权限控制

Configurable autonomy levels
Approval required for destructive operations
Audit logging

可配置的自主级别
破坏性操作需要批准
审计日志

Protected Branches

受保护分支

javascript

const PROTECTED = ['main', 'master', 'develop', 'release/*'];

if (PROTECTED.some(p => branchMatches(p, targetBranch))) {
  throw new Error('Cannot force-push to protected branch');
}

javascript

const PROTECTED = ['main', 'master', 'develop', 'release/*'];

if (PROTECTED.some(p => branchMatches(p, targetBranch))) {
  throw new Error('Cannot force-push to protected branch');
}

Examples

示例

Feature Branch Workflow

功能分支工作流

javascript

// Check current state
const status = await git('status');
if (!status.clean) {
  await git('stash', { action: 'push', message: 'WIP before feature' });
}

// Create feature branch
await git('checkout', {
  newBranch: 'feature/user-auth',
  startPoint: 'main'
});

// Make changes, then commit
await git('add', { files: ['src/auth.js'] });
await git('commit', { message: 'Add authentication module' });

// Push feature branch
await git('push', {
  remote: 'origin',
  branch: 'feature/user-auth',
  setUpstream: true
});

javascript

// 检查当前状态
const status = await git('status');
if (!status.clean) {
  await git('stash', { action: 'push', message: 'WIP before feature' });
}

// 创建功能分支
await git('checkout', {
  newBranch: 'feature/user-auth',
  startPoint: 'main'
});

// 修改代码后提交
await git('add', { files: ['src/auth.js'] });
await git('commit', { message: 'Add authentication module' });

// 推送功能分支
await git('push', {
  remote: 'origin',
  branch: 'feature/user-auth',
  setUpstream: true
});

Review Changes

代码变更审查

javascript

// Get diff of staged changes
const stagedDiff = await git('diff', { cached: true });

// Get log of recent commits
const recentLog = await git('log', { maxEntries: 5 });

// Check if branch is up to date
await git('fetch', { remote: 'origin' });
const behindAhead = await git('rev-list', {
  leftRight: true,
  range: 'HEAD...origin/main'
});

javascript

// 获取已暂存变更的差异
const stagedDiff = await git('diff', { cached: true });

// 获取最近的提交日志
const recentLog = await git('log', { maxEntries: 5 });

// 检查分支是否与远程同步
await git('fetch', { remote: 'origin' });
const behindAhead = await git('rev-list', {
  leftRight: true,
  range: 'HEAD...origin/main'
});

Undo Changes

撤销变更

javascript

// Unstage file
await git('reset', { file: 'src/index.js' });

// Discard working changes
await git('checkout', { file: 'src/index.js' });

// Amend last commit
await git('commit', { amend: true, message: 'Updated message' });

// Soft reset (keep changes staged)
await git('reset', { to: 'HEAD~1', soft: true });

// Hard reset (dangerous!)
await git('reset', { to: 'HEAD~1', hard: true, approved: true });

javascript

// 取消暂存文件
await git('reset', { file: 'src/index.js' });

// 丢弃工作区变更
await git('checkout', { file: 'src/index.js' });

// 修改最后一次提交
await git('commit', { amend: true, message: 'Updated message' });

// 软重置（保留已暂存变更）
await git('reset', { to: 'HEAD~1', soft: true });

// 硬重置（危险操作！）
await git('reset', { to: 'HEAD~1', hard: true, approved: true });

Error Handling

错误处理

javascript

try {
  await git('commit', { message: '' });
} catch (error) {
  if (error.code === 'EMPTY_COMMIT') {
    console.log('Cannot create empty commit');
  } else if (error.code === 'CONFLICT') {
    console.log('Merge conflict detected');
  } else if (error.code === 'UNCOMMITTED_CHANGES') {
    console.log('Stash or commit changes first');
  }
}

javascript

try {
  await git('commit', { message: '' });
} catch (error) {
  if (error.code === 'EMPTY_COMMIT') {
    console.log('Cannot create empty commit');
  } else if (error.code === 'CONFLICT') {
    console.log('Merge conflict detected');
  } else if (error.code === 'UNCOMMITTED_CHANGES') {
    console.log('Stash or commit changes first');
  }
}

Bash CLI

Bash命令行工具

bash

undefined

bash

undefined

Status

状态查询

node /job/.pi/skills/git-structured/git.js --op status

Diff

差异对比

node /job/.pi/skills/git-structured/git.js --op diff --cached

Commit

提交代码

node /job/.pi/skills/git-structured/git.js
--op commit
--message "Add feature"
--files "src/*.js"

Branch

分支操作

node /job/.pi/skills/git-structured/git.js
--op checkout
--new-branch feature/test
--start-point main

undefined

node /job/.pi/skills/git-structured/git.js
--op checkout
--new-branch feature/test
--start-point main

undefined

Output Formats

输出格式

All operations return structured JSON for easy parsing:

Status:

json

{
  "branch": "main",
  "staged": [{"path": "file.js", "status": "M"}],
  "unstaged": [],
  "untracked": [],
  "clean": false
}

Diff:

json

{
  "files": [
    {
      "path": "src/index.js",
      "hunks": [
        {
          "start": 10,
          "changes": [
            {"type": "add", "line": "+ new code"},
            {"type": "remove", "line": "- old code"}
          ]
        }
      ]
    }
  ]
}

Log:

json

[
  {
    "hash": "abc123def456",
    "shortHash": "abc123d",
    "author": "John Doe",
    "email": "john@example.com",
    "date": "2026-02-25T13:30:00Z",
    "message": "Add new feature"
  }
]

所有操作均返回结构化JSON，便于解析：

状态查询结果：

json

{
  "branch": "main",
  "staged": [{"path": "file.js", "status": "M"}],
  "unstaged": [],
  "untracked": [],
  "clean": false
}

差异对比结果：

json

{
  "files": [
    {
      "path": "src/index.js",
      "hunks": [
        {
          "start": 10,
          "changes": [
            {"type": "add", "line": "+ new code"},
            {"type": "remove", "line": "- old code"}
          ]
        }
      ]
    }
  ]
}

提交日志结果：

json

[
  {
    "hash": "abc123def456",
    "shortHash": "abc123d",
    "author": "John Doe",
    "email": "john@example.com",
    "date": "2026-02-25T13:30:00Z",
    "message": "Add new feature"
  }
]