📌 NOTE: For detailed Git 2.49+ features (git-backfill, path-walk API, zlib-ng), see git-2-49-features.md skill.

🚨 CRITICAL GUIDELINES Windows File Path Requirements

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 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 Git 2025 Features - Advanced Capabilities Git 2.49 (March 2025) - Latest

Major additions: git-backfill, path-walk API, zlib-ng performance, improved delta compression.

See git-2-49-features.md for complete coverage.

Git 2.48-2.49 Features Reftables Migration (Completed in 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:

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

When to use:

Repositories with 10,000+ refs High-frequency branch operations CI/CD systems creating many temporary refs Monorepos with extensive branching Performance Milestones (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) Sparse-Checkout (Enhanced in 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):

Clone with sparse-checkout

git clone --filter=blob:none --sparse cd

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

Advanced Patterns (Non-Cone Mode):

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

Reapply Rules:

After merge/rebase that materialized unwanted files

git sparse-checkout reapply

Partial Clone

What: Clone repository without downloading all objects initially.

Filters:

blob:none - Defer all blobs (fastest, smallest) tree:0 - Defer all trees and blobs blob:limit=1m - Defer blobs larger than 1MB

Usage:

Clone without blobs (fetch on demand)

git clone --filter=blob:none

Clone without large files

git clone --filter=blob:limit=10m

Combine with sparse-checkout

git clone --filter=blob:none --sparse cd 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

Combine Partial Clone + Sparse-Checkout:

Ultimate efficiency: Only objects for specific directories

git clone --filter=blob:none --sparse cd git sparse-checkout set --cone src/api git checkout main

Result: Only have objects for src/api

Check promisor objects:

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

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:

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

Advanced Patterns:

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

Best Practices:

Organize directory structure: ~/projects/ myproject/ # Main worktree myproject-feature/ # Feature worktree myproject-review/ # Review worktree

Clean up regularly:

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

Shared configuration: .git/config applies to all worktrees .git/info/exclude applies to all worktrees Each worktree has own index and HEAD Scalar (Large Repository Tool)

What: Tool for optimizing very large repositories (Microsoft-developed).

Install scalar (comes with Git 2.47+)

scalar register

Clone with scalar optimizations

scalar clone --branch main

Enables automatically:

- Sparse-checkout (cone mode)

- Partial clone (blob:none)

- Multi-pack-index

- Commit-graph

- Background maintenance

Unregister

scalar unregister

Delete repository

scalar delete

Git Backfill (Experimental)

What: Background process to fetch missing objects in partial clone.

Fetch missing blobs in background

git backfill

Configure batch size

git backfill --min-batch-size=1000

Respect sparse-checkout patterns

git backfill --sparse

Performance Comparison

Traditional Clone:

git clone large-repo

Size: 5GB, Time: 10 minutes

Sparse-Checkout:

git clone --sparse large-repo git sparse-checkout set src/api

Size: 500MB, Time: 3 minutes

Partial Clone:

git clone --filter=blob:none large-repo

Size: 100MB, Time: 1 minute

Partial Clone + Sparse-Checkout:

git clone --filter=blob:none --sparse large-repo git sparse-checkout set src/api

Size: 50MB, Time: 30 seconds

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 Troubleshooting

Sparse-checkout not working:

Verify configuration

git config core.sparseCheckout git config core.sparseCheckoutCone

Re-apply patterns

git sparse-checkout reapply

Check patterns

git sparse-checkout list

Missing objects in partial clone:

Fetch specific object

git fetch origin

Fetch all missing

git fetch --unshallow

Verify promisor config

git config extensions.partialClone

Worktree issues:

Locked worktree

git worktree unlock

Corrupted worktree

git worktree remove --force git worktree prune

Branch already checked out

git checkout --ignore-other-worktrees

Migration Guide

From traditional to optimized workflow:

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

Resources Git Partial Clone Documentation Git Sparse-Checkout Guide Git Worktree Best Practices Scalar Documentation