📌 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 <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

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 <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

Combine Partial Clone + 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

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 <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 (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 <commit>

Fetch all missing

git fetch --unshallow

Verify promisor config