Back to Details

git-2025-features

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
📌 NOTE: For detailed Git 2.49+ features (git-backfill, path-walk API, zlib-ng), see git-2-49-features.md skill.
📌 注意： 如需了解Git 2.49+的详细功能（git-backfill、path-walk API、zlib-ng），请查看git-2-49-features.md技能文档。

🚨 CRITICAL GUIDELINES

🚨 关键准则

Windows File Path Requirements

Windows文件路径要求

MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (
\
) in file paths, NOT forward slashes (
/
).
Examples:
  • ❌ WRONG: 
    D:/repos/project/file.tsx
  • ✅ CORRECT: 
    D:\repos\project\file.tsx
This applies to:
  • Edit tool file_path parameter
  • Write tool file_path parameter
  • All file operations on Windows systems
强制要求：在Windows系统中始终使用反斜杠表示文件路径
在Windows系统上使用编辑或写入工具时，文件路径必须使用反斜杠（
\
），而不是正斜杠（
/
）。
示例：
  • ❌ 错误：
    D:/repos/project/file.tsx
  • ✅ 正确：
    D:\repos\project\file.tsx
此要求适用于：
  • Edit工具的file_path参数
  • Write工具的file_path参数
  • Windows系统上的所有文件操作

Documentation Guidelines

文档编写准则

NEVER create new documentation files unless explicitly requested by the user.
  • Priority: Update existing README.md files rather than creating new documentation
  • Repository cleanliness: Keep repository root clean - only README.md unless user requests otherwise
  • Style: Documentation should be concise, direct, and professional - avoid AI-generated tone
  • User preference: Only create additional .md files when user specifically asks for documentation
除非用户明确要求，否则绝不要创建新的文档文件。
  • 优先级：优先更新现有的README.md文件，而非创建新文档
  • 仓库整洁性：保持仓库根目录整洁 - 除非用户要求，否则仅保留README.md
  • 风格：文档应简洁、直接、专业 - 避免AI生成的语气
  • 用户偏好：仅在用户明确要求文档时，才创建额外的.md文件

Git 2025 Features - Advanced Capabilities

Git 2025功能 - 高级特性

Git 2.49 (March 2025) - Latest

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

Major additions: git-backfill, path-walk API, zlib-ng performance, improved delta compression.
See git-2-49-features.md for complete coverage.
主要新增功能： git-backfill、path-walk API、zlib-ng性能优化、改进的增量压缩。
完整内容请查看git-2-49-features.md。

Git 2.48-2.49 Features

Git 2.48-2.49功能特性

Reftables Migration (Completed in 2.48)

Reftables迁移（在2.48版本中完成）

What: New reference storage format replacing loose ref files and packed-refs.
Benefits:
  • Faster ref operations (50-80% improvement)
  • Atomic ref updates
  • Better scalability for repositories with many refs
  • Reflogs fully migratable (completed in 2.48)
Migration:
bash
undefined
是什么： 替代松散引用文件和packed-refs的新引用存储格式。
优势：
  • 更快的引用操作（提升50-80%）
  • 原子化引用更新
  • 对拥有大量引用的仓库支持更好的扩展性
  • 引用日志可完全迁移（在2.48版本中完成）
迁移步骤：
bash
undefined

Check current ref storage format

检查当前引用存储格式

git config core.refStorage
git config core.refStorage

Migrate to reftables

迁移到reftables

git refs migrate --ref-storage=reftables
git refs migrate --ref-storage=reftables

Verify migration

验证迁移结果

git fsck --full git log --oneline -5
git fsck --full git log --oneline -5

Roll back if needed (before critical operations)

如有需要可回滚（关键操作前执行）

git refs migrate --ref-storage=files

**When to use:**
- Repositories with 10,000+ refs
- High-frequency branch operations
- CI/CD systems creating many temporary refs
- Monorepos with extensive branching
git refs migrate --ref-storage=files

**适用场景：**
- 拥有10,000+引用的仓库
- 高频分支操作场景
- 创建大量临时引用的CI/CD系统
- 分支结构复杂的单体仓库

Performance Milestones (2.48-2.49)

性能里程碑（2.48-2.49版本）

Git 2.48:
  • Memory leak free status achieved
  • Stable memory usage in long-running operations
Git 2.49:
  • zlib-ng integration: 20-30% faster compression
  • Path-walk API: 50-70% better delta compression
  • New name-hashing algorithm for optimal packfiles
Benefits automatically in:
  • Large repository clones
  • Extended rebase sessions
  • Bulk operations (filter-repo, GC, repack)
Git 2.48：
  • 实现无内存泄漏状态
  • 长时运行操作中内存使用稳定
Git 2.49：
  • zlib-ng集成：压缩速度提升20-30%
  • Path-walk API：增量压缩性能提升50-70%
  • 用于优化打包文件的新名称哈希算法
以下场景会自动受益：
  • 大型仓库克隆
  • 长时间变基会话
  • 批量操作（filter-repo、GC、repack）

Sparse-Checkout (Enhanced in 2.48)

Sparse-Checkout（在2.48版本中增强）

What: Check out only a subset of files from repository.
Use cases:
  • Monorepos (work on one service)
  • Large repositories (reduce disk usage)
  • Build systems (fetch only needed files)
Cone Mode (Default - Recommended):
bash
undefined
是什么： 仅从仓库中检出部分文件。
适用场景：
  • 单体仓库（仅处理某个服务）
  • 大型仓库（减少磁盘占用）
  • 构建系统（仅拉取所需文件）
锥形模式（默认 - 推荐使用）：
bash
undefined

Clone with sparse-checkout

以sparse-checkout方式克隆仓库

git clone --filter=blob:none --sparse <repo-url> cd <repo>
git clone --filter=blob:none --sparse <仓库地址> cd <仓库目录>

Initialize sparse-checkout in cone mode

以锥形模式初始化sparse-checkout

git sparse-checkout init --cone
git sparse-checkout init --cone

Add directories to checkout

添加需要检出的目录

git sparse-checkout set src/api src/shared docs
git sparse-checkout set src/api src/shared docs

Add more directories

添加更多目录

git sparse-checkout add tests/integration
git sparse-checkout add tests/integration

View current patterns

查看当前模式规则

git sparse-checkout list
git sparse-checkout list

Check what would be matched

检查指定文件是否匹配规则

git sparse-checkout check-rules src/api/users.ts
git sparse-checkout check-rules src/api/users.ts

Disable sparse-checkout

禁用sparse-checkout

git sparse-checkout disable

**Advanced Patterns (Non-Cone Mode):**

```bash
git sparse-checkout disable

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

```bash

Enable pattern mode

启用模式匹配模式

git sparse-checkout init --no-cone
git sparse-checkout init --no-cone

Add patterns (one per line)

添加匹配规则（每行一个）

git sparse-checkout set
".md"
"src/api/"
"!src/api/legacy/*"
git sparse-checkout set
".md"
"src/api/"
"!src/api/legacy/*"

Read patterns from file

从文件中读取匹配规则

git sparse-checkout set --stdin < patterns.txt

**Reapply Rules:**

```bash
git sparse-checkout set --stdin < patterns.txt

**重新应用规则：**

```bash

After merge/rebase that materialized unwanted files

在合并/变基后出现不需要的文件时，重新应用规则

git sparse-checkout reapply
undefined
git sparse-checkout reapply
undefined

Partial Clone

Partial Clone

What: Clone repository without downloading all objects initially.
Filters:
  1. blob:none - Defer all blobs (fastest, smallest)
  2. tree:0 - Defer all trees and blobs
  3. blob:limit=1m - Defer blobs larger than 1MB
Usage:
bash
undefined
是什么： 初始克隆时不下载所有对象。
过滤选项：
  1. blob:none - 延迟所有大文件（速度最快，占用最小）
  2. tree:0 - 延迟所有树和大文件
  3. blob:limit=1m - 延迟大于1MB的大文件
使用方法：
bash
undefined

Clone without blobs (fetch on demand)

克隆时不下载大文件（按需获取）

git clone --filter=blob:none <repo-url>
git clone --filter=blob:none <仓库地址>

Clone without large files

克隆时排除大文件

git clone --filter=blob:limit=10m <repo-url>
git clone --filter=blob:limit=10m <仓库地址>

Combine with sparse-checkout

结合sparse-checkout使用

git clone --filter=blob:none --sparse <repo-url> cd <repo> git sparse-checkout set src/api
git clone --filter=blob:none --sparse <仓库地址> cd <仓库目录> git sparse-checkout set src/api

Convert existing repository to partial clone

将现有仓库转换为partial clone

git config extensions.partialClone origin git config remote.origin.promisor true git fetch --filter=blob:none
git config extensions.partialClone origin git config remote.origin.promisor true git fetch --filter=blob:none

Prefetch all missing objects

预取所有缺失的对象

git fetch --unshallow

**Combine Partial Clone + Sparse-Checkout:**

```bash
git fetch --unshallow

**结合Partial Clone + Sparse-Checkout：**

```bash

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
git clone --filter=blob:none --sparse <仓库地址> cd <仓库目录> git sparse-checkout set --cone src/api git checkout main

Result: Only have objects for src/api

结果：仅拥有src/api目录的对象


**Check promisor objects:**

```bash

**检查promisor对象：**

```bash

Verify partial clone status

验证partial clone状态

git config extensions.partialClone
git config extensions.partialClone

See promisor packfiles

查看promisor打包文件

ls -lah .git/objects/pack/*.promisor
ls -lah .git/objects/pack/*.promisor

Force fetch specific object

强制获取特定对象

git rev-list --objects --missing=print HEAD | grep "^?"
undefined
git rev-list --objects --missing=print HEAD | grep "^?"
undefined

Git Worktrees

Git Worktrees

What: Multiple working directories from one repository.
Benefits:
  • Work on multiple branches simultaneously
  • No need to stash/commit before switching
  • Parallel work (review PR while coding)
  • Shared .git (one fetch updates all)
Basic Operations:
bash
undefined
是什么： 从一个仓库创建多个工作目录。
优势：
  • 同时处理多个分支
  • 切换分支前无需暂存/提交
  • 并行工作（审核PR的同时编写代码）
  • 共享.git目录（一次拉取更新所有工作目录）
基础操作：
bash
undefined

List worktrees

列出所有工作树

git worktree list
git worktree list

Create worktree for existing branch

为已有分支创建工作树

git worktree add ../project-feature feature-branch
git worktree add ../project-feature feature-branch

Create worktree with new branch

创建工作树并同时新建分支

git worktree add -b new-feature ../project-new-feature
git worktree add -b new-feature ../project-new-feature

Create worktree from remote branch

为远程分支创建工作树

git worktree add ../project-fix origin/fix-bug
git worktree add ../project-fix origin/fix-bug

Remove worktree

删除工作树

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

Clean up stale worktree references

清理过期的工作树引用

git worktree prune

**Advanced Patterns:**

```bash
git worktree prune

**高级使用模式：**

```bash

Worktree for PR review while coding

编写代码时同时审核PR的工作树

git worktree add ../myproject-pr-123 origin/pull/123/head cd ../myproject-pr-123
git worktree add ../myproject-pr-123 origin/pull/123/head cd ../myproject-pr-123

Review PR in separate directory

在独立目录中审核PR

cd -
cd -

Continue coding in main worktree

在主工作树中继续编写代码

Worktree for hotfix

用于热修复的工作树

git worktree add --detach ../myproject-hotfix v1.2.3 cd ../myproject-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
git switch -c hotfix/security-patch git commit -am "fix: 修复漏洞" 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

**Best Practices:**

1. **Organize directory structure:**
```bash
~/projects/
  myproject/           # Main worktree
  myproject-feature/   # Feature worktree
  myproject-review/    # Review worktree
  1. Clean up regularly:
bash
undefined
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. **组织目录结构：**
```bash
~/projects/
  myproject/           # 主工作树
  myproject-feature/   # 功能开发工作树
  myproject-review/    # PR审核工作树
  1. 定期清理：
bash
undefined

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. **Shared configuration:**
- .git/config applies to all worktrees
- .git/info/exclude applies to all worktrees
- Each worktree has own index and HEAD
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 对所有工作树生效
- 每个工作树有独立的索引和HEAD

Scalar (Large Repository Tool)

Scalar（大型仓库工具）

What: Tool for optimizing very large repositories (Microsoft-developed).
bash
undefined
是什么： 用于优化超大型仓库的工具（由微软开发）。
bash
undefined

Install scalar (comes with Git 2.47+)

安装Scalar（Git 2.47+已内置）

scalar register <path>
scalar register <路径>

Clone with scalar optimizations

以Scalar优化方式克隆仓库

scalar clone --branch main <repo-url>
scalar clone --branch main <仓库地址>

Enables automatically:

自动启用以下功能：

- Sparse-checkout (cone mode)

- Sparse-checkout（锥形模式）

- Partial clone (blob:none)

- Partial clone（blob:none）

- Multi-pack-index

- 多打包索引（Multi-pack-index）

- Commit-graph

- 提交图（Commit-graph）

- Background maintenance

- 后台维护

Unregister

取消注册

scalar unregister <path>
scalar unregister <路径>

Delete repository

删除仓库

scalar delete <path>
undefined
scalar delete <路径>
undefined

Git Backfill (Experimental)

Git Backfill（实验性功能）

What: Background process to fetch missing objects in partial clone.
bash
undefined
是什么： 在partial clone中后台获取缺失对象的进程。
bash
undefined

Fetch missing blobs in background

后台获取缺失的大文件

git backfill
git backfill

Configure batch size

配置批量大小

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

Respect sparse-checkout patterns

遵循sparse-checkout规则

git backfill --sparse
undefined
git backfill --sparse
undefined

Performance Comparison

性能对比

Traditional Clone:
bash
git clone large-repo
传统克隆：
bash
git clone large-repo

Size: 5GB, Time: 10 minutes

大小：5GB，时间：10分钟


**Sparse-Checkout:**
```bash
git clone --sparse large-repo
git sparse-checkout set src/api

**Sparse-Checkout：**
```bash
git clone --sparse large-repo
git sparse-checkout set src/api

Size: 500MB, Time: 3 minutes

大小：500MB，时间：3分钟


**Partial Clone:**
```bash
git clone --filter=blob:none large-repo

**Partial Clone：**
```bash
git clone --filter=blob:none large-repo

Size: 100MB, Time: 1 minute

大小：100MB，时间：1分钟


**Partial Clone + Sparse-Checkout:**
```bash
git clone --filter=blob:none --sparse large-repo
git sparse-checkout set src/api

**Partial Clone + Sparse-Checkout：**
```bash
git clone --filter=blob:none --sparse large-repo
git sparse-checkout set src/api

Size: 50MB, Time: 30 seconds

大小：50MB，时间：30秒

undefined
undefined

When to Use Each Feature

各功能适用场景

Sparse-Checkout:
  • ✓ Monorepos
  • ✓ Working on specific services/modules
  • ✓ Limited disk space
  • ✗ Need entire codebase often
Partial Clone:
  • ✓ CI/CD pipelines
  • ✓ Large repositories
  • ✓ Good network connectivity
  • ✗ Offline work frequently
Worktrees:
  • ✓ Parallel development
  • ✓ PR reviews during work
  • ✓ Multiple branch testing
  • ✗ Low disk space
Combine All:
  • ✓ Massive monorepos (Google scale)
  • ✓ Multiple simultaneous tasks
  • ✓ Minimal local storage
  • ✓ Fast network connection
Sparse-Checkout：
  • ✓ 单体仓库
  • ✓ 仅处理特定服务/模块
  • ✓ 磁盘空间有限
  • ✗ 经常需要完整代码库
Partial Clone：
  • ✓ CI/CD流水线
  • ✓ 大型仓库
  • ✓ 网络连接良好
  • ✗ 频繁离线工作
Worktrees：
  • ✓ 并行开发
  • ✓ 工作期间审核PR
  • ✓ 多分支测试
  • ✗ 磁盘空间不足
组合使用所有功能：
  • ✓ 超大规模单体仓库（谷歌级别）
  • ✓ 同时处理多项任务
  • ✓ 本地存储占用最小化
  • ✓ 网络连接快速

Troubleshooting

故障排除

Sparse-checkout not working:
bash
undefined
Sparse-checkout不生效：
bash
undefined

Verify configuration

验证配置

git config core.sparseCheckout git config core.sparseCheckoutCone
git config core.sparseCheckout git config core.sparseCheckoutCone

Re-apply patterns

重新应用规则

git sparse-checkout reapply
git sparse-checkout reapply

Check patterns

检查规则

git sparse-checkout list

**Missing objects in partial clone:**
```bash
git sparse-checkout list

**Partial Clone中缺失对象：**
```bash

Fetch specific object

获取特定对象

git fetch origin <commit>
git fetch origin <提交哈希>

Fetch all missing

获取所有缺失对象

git fetch --unshallow
git fetch --unshallow

Verify promisor config

验证promisor配置

git config extensions.partialClone

**Worktree issues:**
```bash
git config extensions.partialClone

**Worktree问题：**
```bash

Locked worktree

解锁被锁定的工作树

git worktree unlock <path>
git worktree unlock <路径>

Corrupted worktree

删除损坏的工作树

git worktree remove --force <path> git worktree prune
git worktree remove --force <路径> git worktree prune

Branch already checked out

分支已被其他工作树检出时

git checkout --ignore-other-worktrees <branch>
undefined
git checkout --ignore-other-worktrees <分支名>
undefined

Migration Guide

迁移指南

From traditional to optimized workflow:
bash
undefined
从传统工作流迁移到优化工作流：
bash
undefined

1. Current large clone

1. 当前的大型克隆仓库

cd large-project du -sh .git # 5GB
cd large-project du -sh .git # 5GB

2. Create optimized new clone

2. 创建优化后的新克隆

cd .. git clone --filter=blob:none --sparse large-project-new cd large-project-new git sparse-checkout set src/api src/shared
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

3. 验证大小

du -sh .git # 50MB
du -sh .git # 50MB

4. Switch workflow

4. 切换到新工作流

cd ../large-project-new
cd ../large-project-new

5. Delete old clone when comfortable

5. 确认无误后删除旧克隆

rm -rf ../large-project
undefined
rm -rf ../large-project
undefined

Resources

资源