automaker/libs/git-utils/README.md

# @automaker/git-utils

Git operations and utilities for AutoMaker.

## Overview

This package provides git-related utilities including repository detection, status parsing, and diff generation for both tracked and untracked files.

## Installation

```bash
npm install @automaker/git-utils
```

## Exports

### Repository Detection
Check if a path is a git repository.

```typescript
import { isGitRepo } from '@automaker/git-utils';

const isRepo = await isGitRepo('/project/path');
if (isRepo) {
  console.log('This is a git repository');
}
```

### Status Parsing
Parse git status output into structured data.

```typescript
import { parseGitStatus } from '@automaker/git-utils';
import type { FileStatus } from '@automaker/git-utils';

const statusOutput = await execAsync('git status --porcelain');
const files: FileStatus[] = parseGitStatus(statusOutput.stdout);

files.forEach(file => {
  console.log(`${file.statusText}: ${file.path}`);
  // Example: "Modified: src/index.ts"
  // Example: "Untracked: new-file.ts"
});
```

### Diff Generation
Generate diffs including untracked files.

```typescript
import {
  generateSyntheticDiffForNewFile,
  appendUntrackedFileDiffs,
  getGitRepositoryDiffs
} from '@automaker/git-utils';

// Generate diff for single untracked file
const diff = await generateSyntheticDiffForNewFile(
  '/project/path',
  'src/new-file.ts'
);

// Get complete repository diffs (tracked + untracked)
const result = await getGitRepositoryDiffs('/project/path');
console.log(result.diff);        // Combined diff string
console.log(result.files);       // Array of FileStatus
console.log(result.hasChanges);  // Boolean
```

### Non-Git Directory Support
Handle non-git directories by treating all files as new.

```typescript
import {
  listAllFilesInDirectory,
  generateDiffsForNonGitDirectory
} from '@automaker/git-utils';

// List all files (excluding build artifacts)
const files = await listAllFilesInDirectory('/project/path');

// Generate diffs for non-git directory
const result = await generateDiffsForNonGitDirectory('/project/path');
console.log(result.diff);   // Synthetic diffs for all files
console.log(result.files);  // All files as "New" status
```

## Types

### FileStatus
```typescript
interface FileStatus {
  status: string;      // Git status code (M/A/D/R/C/U/?/!)
  path: string;        // File path relative to repo root
  statusText: string;  // Human-readable status
}
```

### Status Codes
- `M` - Modified
- `A` - Added
- `D` - Deleted
- `R` - Renamed
- `C` - Copied
- `U` - Updated
- `?` - Untracked
- `!` - Ignored
- ` ` - Unmodified

### Status Text Examples
- `"Modified"` - File has changes
- `"Added"` - New file in staging
- `"Deleted"` - File removed
- `"Renamed"` - File renamed
- `"Untracked"` - New file not in git
- `"Modified (staged), Modified (unstaged)"` - Changes in both areas

## Usage Example

```typescript
import {
  isGitRepo,
  getGitRepositoryDiffs,
  parseGitStatus
} from '@automaker/git-utils';

async function getProjectChanges(projectPath: string) {
  const isRepo = await isGitRepo(projectPath);

  if (!isRepo) {
    console.log('Not a git repository, analyzing all files...');
  }

  const result = await getGitRepositoryDiffs(projectPath);

  if (!result.hasChanges) {
    console.log('No changes detected');
    return;
  }

  console.log(`Found ${result.files.length} changed files:\n`);

  // Group by status
  const byStatus = result.files.reduce((acc, file) => {
    acc[file.statusText] = acc[file.statusText] || [];
    acc[file.statusText].push(file.path);
    return acc;
  }, {} as Record<string, string[]>);

  Object.entries(byStatus).forEach(([status, paths]) => {
    console.log(`${status}:`);
    paths.forEach(path => console.log(`  - ${path}`));
  });

  return result.diff;
}
```

## Features

### Binary File Detection
Automatically detects binary files by extension and generates appropriate diff markers.

**Supported binary extensions:**
- Images: `.png`, `.jpg`, `.jpeg`, `.gif`, `.svg`, etc.
- Documents: `.pdf`, `.doc`, `.docx`, etc.
- Archives: `.zip`, `.tar`, `.gz`, etc.
- Media: `.mp3`, `.mp4`, `.wav`, etc.
- Fonts: `.ttf`, `.otf`, `.woff`, etc.

### Large File Handling
Files larger than 1MB show size information instead of full content.

### Synthetic Diff Format
Generates unified diff format for untracked files:
```diff
diff --git a/new-file.ts b/new-file.ts
new file mode 100644
index 0000000..0000000
--- /dev/null
+++ b/new-file.ts
@@ -0,0 +1,10 @@
+export function hello() {
+  console.log('Hello');
+}
```

### Directory Filtering
When scanning non-git directories, automatically excludes:
- `node_modules`
- `.git`
- `.automaker`
- `dist`, `build`
- `.next`, `.nuxt`
- `__pycache__`, `.cache`
- `coverage`

## Dependencies

- `@automaker/types` - FileStatus type definition
- `@automaker/utils` - Logger utilities

## Used By

- `@automaker/server` - Git routes, worktree operations, feature context