Skip to content

CLAUDE.md

Latest commit

 

History

History
91 lines (64 loc) · 2.73 KB

CLAUDE.md

File metadata and controls

91 lines (64 loc) · 2.73 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

git-split is a Python CLI tool that splits a file into multiple files while preserving git blame line history. It uses temporary git branches and octopus merges so that git tracks the lineage of each line through the split.

Package Structure

git_split/
  __init__.py        # version, top-level imports
  core.py            # pure logic: parse_range, detect_split_blocks, process_file, analyze_split
  git_ops.py         # git interaction: run_git_command, ensure_clean_worktree, move_file_and_commit
  cli.py             # argparse main(), execute_split_plan()
  exceptions.py      # GitSplitError, GitCommandError, ParseError
  mcp_server.py      # FastMCP server with tools + resource
  __main__.py         # python -m git_split
tests/
  test_core.py        # test parse_range, detect_split_blocks, process_file
  test_git_ops.py     # test run_git_command, ensure_clean_worktree

Running

# Install in development mode:
pip install -e .

# Run with inline SPLIT markers (autodetect mode):
git-split source_file.py

# Run with explicit line ranges (manual mode):
git-split "source.py:10-20:new_file.py"

# Preview changes:
git-split -p source_file.py

# Dry run (no git operations executed):
git-split -n source_file.py

# Skip confirmation prompt:
git-split -y source_file.py

# Run as module:
python -m git_split source_file.py

# Start MCP server:
git-split-mcp

Running Tests

pytest tests/ -v

Dependencies

  • Python >=3.9
  • intervaltree>=3.0 — tracking line ranges
  • tabulate>=0.9 — formatting change digest output
  • Optional: mcp>=1.0 — for MCP server functionality

Install with: pip install -e ".[dev]" (includes pytest)

Architecture

Two modes of operation

  1. Autodetect mode — scans for SPLIT:EXTRACT:<target> / SPLIT:ENDBLOCK comment markers
  2. Manual mode — old_file:line_range:new_file format

Both build an IntervalTree and converge on process_file().

Git history preservation strategy

  1. For each target file, create a temp branch and git mv source -> target
  2. Octopus merge all temp branches
  3. Rename temp copies back to original names
  4. Overwrite each file with only its designated lines
  5. Merge final branch back with --no-ff
  6. Clean up temp branches

Key modules

  • core.py — Pure logic: parse_range, detect_split_blocks, process_file, analyze_split
  • git_ops.py — Git commands via subprocess (list-based, no shell=True), ensure_clean_worktree
  • cli.py — CLI entry point, execute_split_plan() orchestration
  • mcp_server.py — MCP tools: detect_blocks, preview_split, execute_split