git-2025-features

📌 注意： 如需了解 Git 2.49+ 的详细功能（git-backfill、path-walk API、zlib-ng），请参阅 git-2-49-features.md 技能。

🚨 关键指南

Windows 文件路径要求

必须：在 Windows 上始终使用反斜杠表示文件路径

在 Windows 上使用 Edit 或 Write 工具时，文件路径必须使用反斜杠（\），而不是正斜杠（/）。

示例：

• ❌ 错误：D:/repos/project/file.tsx
• ✅ 正确：D:\repos\project\file.tsx

适用于：

• Edit 工具的 file_path 参数
• Write 工具的 file_path 参数
• Windows 系统上的所有文件操作

文档指南

除非用户明确要求，否则绝不创建新的文档文件。

• 优先事项： 更新现有的 README.md 文件，而不是创建新文档
• 保持仓库整洁： 保持仓库根目录整洁——除非用户另有要求，否则只保留 README.md
• 风格： 文档应简洁、直接且专业，避免 AI 生成的语气
• 用户偏好： 仅在用户明确要求提供文档时，才创建其他 .md 文件

---

Git 2025 年功能——高级能力

Git 2.49（2025 年 3 月）——最新版本

主要新增功能： git-backfill、path-walk API、zlib-ng 性能优化、改进的增量压缩。

完整内容请参阅 git-2-49-features.md。

Git 2.48-2.49 功能

Reftables 迁移（在 2.48 中完成）

是什么： 一种新的引用存储格式，取代松散引用文件和 packed-refs。

优点：

• 引用操作更快（提升 50-80%）
• 引用更新具有原子性
• 更适合包含大量引用的仓库，扩展性更好
• Reflog 可完整迁移（在 2.48 中完成）

迁移：

# Check current ref storage format
git config core.refStorage

# Migrate to reftables
git refs migrate --ref-storage=reftables

# Verify migration
git fsck --full
git log --oneline -5

# Roll back if needed (before critical operations)
git refs migrate --ref-storage=files

适用场景：

• 拥有 10,000+ 个引用的仓库
• 高频分支操作
• 创建大量临时引用的 CI/CD 系统
• 分支众多的 Monorepo

性能里程碑（2.48-2.49）

Git 2.48：

• 实现无内存泄漏的状态
• 长时间运行的操作中内存使用稳定

Git 2.49：

• 集成 zlib-ng：压缩速度提升 20-30%
• Path-walk API：增量压缩效果提升 50-70%
• 新的名称哈希算法，可生成最优 packfile

以下场景会自动受益：

• 大型仓库克隆
• 长时间的 rebase 会话
• 批量操作（filter-repo、GC、repack）

Sparse-Checkout（在 2.48 中增强）

是什么： 仅从仓库中检出一部分文件。

适用场景：

• Monorepo（只处理一个服务）
• 大型仓库（减少磁盘占用）
• 构建系统（仅获取所需文件）

锥形模式（默认——推荐）：

# Clone with sparse-checkout
git clone --filter=blob:none --sparse <repo-url>
cd <repo>

# Initialize sparse-checkout in cone mode
git sparse-checkout init --cone

# Add directories to checkout
git sparse-checkout set src/api src/shared docs

# Add more directories
git sparse-checkout add tests/integration

# View current patterns
git sparse-checkout list

# Check what would be matched
git sparse-checkout check-rules src/api/users.ts

# Disable sparse-checkout
git sparse-checkout disable

高级模式（非锥形模式）：

# Enable pattern mode
git sparse-checkout init --no-cone

# Add patterns (one per line)
git sparse-checkout set \
  "*.md" \
  "src/api/*" \
  "!src/api/legacy/*"

# Read patterns from file
git sparse-checkout set --stdin < patterns.txt

重新应用规则：

# After merge/rebase that materialized unwanted files
git sparse-checkout reapply

部分克隆

是什么： 初始克隆仓库时不下载所有对象。

筛选器：

1. blob:none - 延迟获取所有 blob（最快、体积最小）
2. tree:0 - 延迟获取所有 tree 和 blob
3. blob:limit=1m - 延迟获取大于 1MB 的 blob

用法：

# Clone without blobs (fetch on demand)
git clone --filter=blob:none <repo-url>

# Clone without large files
git clone --filter=blob:limit=10m <repo-url>

# Combine with sparse-checkout
git clone --filter=blob:none --sparse <repo-url>
cd <repo>
git sparse-checkout set src/api

# Convert existing repository to partial clone
git config extensions.partialClone origin
git config remote.origin.promisor true
git fetch --filter=blob:none

# Prefetch all missing objects
git fetch --unshallow

组合使用部分克隆和 Sparse-Checkout：

# Ultimate efficiency: Only objects for specific directories
git clone --filter=blob:none --sparse <repo-url>
cd <repo>
git sparse-checkout set --cone src/api
git checkout main

# Result: Only have objects for src/api

检查 promisor 对象：

# Verify partial clone status
git config extensions.partialClone

# See promisor packfiles
ls -lah .git/objects/pack/*.promisor

# Force fetch specific object
git rev-list --objects --missing=print HEAD | grep "^?"

Git Worktrees

是什么： 从一个仓库创建多个工作目录。

优点：

• 同时处理多个分支
• 切换前无需暂存或提交
• 并行工作（编码时审查 PR）
• 共享 .git（一次 fetch 即可更新全部工作树）

基本操作：

# List worktrees
git worktree list

# Create worktree for existing branch
git worktree add ../project-feature feature-branch

# Create worktree with new branch
git worktree add -b new-feature ../project-new-feature

# Create worktree from remote branch
git worktree add ../project-fix origin/fix-bug

# Remove worktree
git worktree remove ../project-feature

# Clean up stale worktree references
git worktree prune

高级模式：

# Worktree for PR review while coding
git worktree add ../myproject-pr-123 origin/pull/123/head
cd ../myproject-pr-123
# Review PR in separate directory
cd -
# Continue coding in main worktree

# Worktree for hotfix
git worktree add --detach ../myproject-hotfix v1.2.3
cd ../myproject-hotfix
# Make hotfix
git switch -c hotfix/security-patch
git commit -am "fix: patch vulnerability"
git push -u origin hotfix/security-patch

# Worktree organization
mkdir -p ~/worktrees/myproject
git worktree add ~/worktrees/myproject/feature-a -b feature-a
git worktree add ~/worktrees/myproject/feature-b -b feature-b
git worktree add ~/worktrees/myproject/pr-review origin/pull/42/head

最佳实践：

1. 组织目录结构：

~/projects/
  myproject/           # Main worktree
  myproject-feature/   # Feature worktree
  myproject-review/    # Review worktree

2. 定期清理：

# Remove merged worktrees
git worktree list | grep feature | while read wt branch commit; do
  if git branch --merged | grep -q "$branch"; then
    git worktree remove "$wt"
  fi
done

3. 共享配置：

• .git/config 适用于所有工作树
• .git/info/exclude 适用于所有工作树
• 每个工作树都有自己的 index 和 HEAD

Scalar（大型仓库工具）

是什么： 用于优化超大型仓库的工具（由 Microsoft 开发）。

# Install scalar (comes with Git 2.47+)
scalar register <path>

# Clone with scalar optimizations
scalar clone --branch main <repo-url>

# Enables automatically:
# - Sparse-checkout (cone mode)
# - Partial clone (blob:none)
# - Multi-pack-index
# - Commit-graph
# - Background maintenance

# Unregister
scalar unregister <path>

# Delete repository
scalar delete <path>

Git Backfill（实验性）

是什么： 用于在后台进程中获取部分克隆所缺少对象的工具。

# Fetch missing blobs in background
git backfill

# Configure batch size
git backfill --min-batch-size=1000

# Respect sparse-checkout patterns
git backfill --sparse

性能对比

传统克隆：

git clone large-repo
# Size: 5GB, Time: 10 minutes

稀疏检出：

git clone --sparse large-repo
git sparse-checkout set src/api
# Size: 500MB, Time: 3 minutes

部分克隆：

git clone --filter=blob:none large-repo
# Size: 100MB, Time: 1 minute

部分克隆 + 稀疏检出：

git clone --filter=blob:none --sparse large-repo
git sparse-checkout set src/api
# Size: 50MB, Time: 30 seconds

何时使用各项功能

稀疏检出：

• ✓ 单体仓库
• ✓ 处理特定服务/模块
• ✓ 磁盘空间有限
• ✗ 经常需要整个代码库

部分克隆：

• ✓ CI/CD 流水线
• ✓ 大型仓库
• ✓ 网络连接良好
• ✗ 经常离线工作

工作树：

• ✓ 并行开发
• ✓ 工作期间审查 PR
• ✓ 测试多个分支
• ✗ 磁盘空间不足

组合使用：

• ✓ 超大型单体仓库（Google 规模）
• ✓ 同时处理多个任务
• ✓ 尽量减少本地存储
• ✓ 网络连接快速

故障排除

稀疏检出无法正常工作：

# Verify configuration
git config core.sparseCheckout
git config core.sparseCheckoutCone

# Re-apply patterns
git sparse-checkout reapply

# Check patterns
git sparse-checkout list

部分克隆中缺少对象：

# Fetch specific object
git fetch origin <commit>

# Fetch all missing
git fetch --unshallow

# Verify promisor config
git config extensions.partialClone

工作树问题：

# Locked worktree
git worktree unlock <path>

# Corrupted worktree
git worktree remove --force <path>
git worktree prune

# Branch already checked out
git checkout --ignore-other-worktrees <branch>

迁移指南

从传统工作流迁移到优化工作流：

# 1. Current large clone
cd large-project
du -sh .git  # 5GB

# 2. Create optimized new clone
cd ..
git clone --filter=blob:none --sparse large-project-new
cd large-project-new
git sparse-checkout set src/api src/shared

# 3. Verify size
du -sh .git  # 50MB

# 4. Switch workflow
cd ../large-project-new

# 5. Delete old clone when comfortable
rm -rf ../large-project

资源

• Git 部分克隆文档
• Git 稀疏检出指南
• Git 工作树最佳实践
• Scalar 文档