Feature: Tagging, Stashing, and Ref Management

[BishopMowle]

Overview

Implement tagging, stashing, and reference management operations to match isomorphic-git feature parity.

Commands to Implement

• tag - Create a tag (lightweight or annotated)
• annotatedTag - Create an annotated tag with message
• deleteTag - Delete a tag
• listTags - List all tags
• stash - Stash changes in working directory
• stashList - List stashes
• stashPop - Apply and remove stash
• expandRef - Expand a shortened ref to full name
• expandOid - Expand a shortened OID to full hash
• deleteRef - Delete a reference

Acceptance Criteria (AC)

1. AC1: Tag Creation - Can create both lightweight and annotated tags
2. AC2: Tag Listing/Deletion - Can list all tags and delete specific tags
3. AC3: Stash Functionality - Can stash, list, and pop stashes preserving working tree state
4. AC4: Ref Expansion - Can expand short refs (e.g., "main") to full refs ("refs/heads/main")
5. AC5: Ref Deletion - Can safely delete refs (branches, tags)
6. AC6: Type Safety - All functions properly typed with strict TypeScript

Definition of Done (DoD)

• All commands implemented
• Unit tests >80% coverage
• Interop tests passing
• Documentation updated
• No TypeScript errors

Interop Test Method

// Test tags
await tsGit.tag({ fs, dir: repoDir, ref: 'v1.0.0', object: 'HEAD', message: 'Release 1.0.0' });
const tsGitTags = await tsGit.listTags({ fs, dir: repoDir });

// Compare with canonical git
execSync('git tag -a v1.0.0 -m "Release 1.0.0"', { cwd: '/tmp/ref-repo' });
const refTags = execSync('git tag -l', { cwd: '/tmp/ref-repo' }).toString().split('\n');

// Assertions: tsGitTags should match refTags

Validation Strategy:

1. Create tags/stashes with ts-git and canonical git
2. Compare ref storage (.git/refs/tags/, .git/refs/stash)
3. Verify tag objects (for annotated tags) match
4. Test stash reflog behavior

Priority

Medium - Important for release workflows and developer convenience

Dependencies

• Requires object storage (tag objects)
• Stash requires index manipulation