Remove Co-author Functionality

[pawelma]

Remove Co-author Functionality

This document describes the new co-author removal functionality added to git-pair, which allows for granular management of co-authors during pair programming sessions.

Overview

The git pair remove command enables selective removal of co-authors from the current branch, providing more flexibility than the existing git pair clear command which removes all co-authors at once. This feature is particularly useful during:

• Mob programming sessions where team members join and leave dynamically
• Long-running features where different specialists contribute at different phases
• Flexible team collaboration where co-author lists need frequent adjustments

Features

Multiple Removal Methods

The remove command supports three different ways to identify and remove co-authors:

1. By Full Name: Remove using the complete name as it appears in commits
2. By Email Address: Remove using the email address
3. By Global Alias: Remove using the alias from your global roster

Case-Insensitive Matching

Name-based removal is case-insensitive, making it more user-friendly:

• git pair remove "john doe" matches John Doe
• git pair remove "ALICE JOHNSON" matches Alice Johnson

Smart Hook Management

The git hook is automatically managed when co-authors are removed:

• Updates hook: When some co-authors remain after removal
• Removes hook: When the last co-author is removed (returns to solo mode)
• Preserves existing hooks: Only removes git-pair sections, keeps other hook content

Usage

Basic Syntax

git pair remove <identifier>

Where <identifier> can be:

• Full name (in quotes if contains spaces)
• Email address
• Global roster alias

Examples

Remove by Name

# Remove co-author by full name
git pair remove "Alice Johnson"

# Case-insensitive matching
git pair remove "alice johnson"
git pair remove "ALICE JOHNSON"

Remove by Email

# Remove co-author by email address
git pair remove alice.johnson@company.com
git pair remove bob@example.org

Remove by Global Alias

# Remove co-author using their global roster alias
git pair remove alice
git pair remove bob

# This works if 'alice' exists in your global roster
# and was previously added to the current branch

Workflow Examples

Dynamic Mob Programming

# Start with full team
git pair init
git pair add alice bob carol dave

# Alice leaves after initial planning
git pair remove alice

# Make some commits with remaining team
git commit -m "Implement core structure"

# Dave needs to leave for a meeting
git pair remove dave

# Continue with bob and carol
git commit -m "Add validation logic"

# Dave returns, Alice doesn't
git pair add dave

# Final implementation with bob, carol, and dave
git commit -m "Complete feature implementation"

Specialist Contributions

# Start feature branch with backend developers
git pair init
git pair add backend_alice backend_bob

# Backend work complete, frontend developer joins
git pair remove backend_alice
git pair remove backend_bob
git pair add frontend_carol

# Frontend work complete, add QA engineer
git pair remove frontend_carol
git pair add qa_dave

# Final touches with original backend developer
git pair remove qa_dave
git pair add backend_alice

Error Recovery

# Accidentally added wrong person
git pair add wrong_person@company.com

# Remove the wrong addition
git pair remove wrong_person@company.com

# Add the correct person
git pair add correct_person@company.com

Error Handling

The remove command provides clear error messages for various scenarios:

Co-author Not Found

$ git pair remove "Unknown Person"
Error: Co-author 'Unknown Person' not found on branch 'main'. Use 'git-pair status' to see current co-authors.

Global Alias Not Found

$ git pair remove unknown_alias
Error: Co-author 'unknown_alias' not found on branch 'main'. Use 'git-pair status' to see current co-authors.

Not Initialized

$ git pair remove alice
Error: git-pair not initialized for branch 'main'. Please run 'git-pair init' first.

Usage Help

$ git pair remove
Usage: git-pair remove <name|email|alias>
Examples:
  git-pair remove "John Doe"
  git-pair remove john.doe@example.com
  git-pair remove alice

Technical Implementation

Matching Logic

The remove functionality uses a hierarchical matching approach:

1. Direct Matching: First attempts to match the identifier directly in co-author lines
2. Case-insensitive Name Matching: For name-based removal, converts both the search term and stored names to lowercase
3. Email Matching: Exact email address matching
4. Global Alias Resolution: If direct matching fails, checks if the identifier is a global roster alias and attempts to match the corresponding name/email

Hook Management

The git hook is intelligently managed during removal operations:

// Pseudo-code for hook management logic
if remaining_coauthors.is_empty() {
    remove_git_hook();  // Return to solo mode
} else {
    update_git_hook();  // Update with remaining co-authors
}

File Operations

Co-author removal modifies the branch-specific configuration file (.git/git-pair/config-{branch_name}):

1. Read: Current configuration file
2. Filter: Remove matching co-author lines
3. Reconstruct: Rebuild file with header and remaining co-authors
4. Write: Update the configuration file
5. Hook Update: Refresh git hook based on remaining co-authors

Integration with Existing Features

Compatibility with Global Roster

The remove command seamlessly integrates with the global roster feature:

# Add from global roster
git pair add alice bob

# Remove using the same aliases
git pair remove alice

# Bob remains, alice is removed
git pair status  # Shows only bob

Per-Branch Isolation

Removal is branch-specific and doesn't affect other branches:

# On feature branch
git pair add alice bob
git pair remove alice  # Only removes from current branch

# Switch to main branch
git checkout main
git pair status  # Alice might still be configured here if added separately

Status Integration

The git pair status command shows the current state after removals:

$ git pair status
Current co-authors:
  Co-authored-by: Bob Wilson <bob@company.com>
  Co-authored-by: Carol Davis <carol@company.com>

Best Practices

1. Use Meaningful Identifiers

Choose the most convenient identifier based on context:

• Names: When you remember the person's name
• Emails: When working with external contributors with unfamiliar names
• Aliases: When using your established global roster

2. Verify Before Committing

Always check status after making changes:

git pair remove alice
git pair status  # Verify the removal was correct
git commit -m "Your commit message"

3. Communicate Changes

When working in teams, communicate co-author changes:

# Before removing someone
echo "Removing Alice from pair session"
git pair remove alice

4. Use Clear Commit Messages

Document team changes in your commit messages:

git commit -m "Implement authentication (Alice left session early)"

Comparison with Clear Command

Aspect	git pair remove	git pair clear
Scope	Removes specific co-author	Removes all co-authors
Precision	Granular control	All-or-nothing
Use Case	Dynamic team changes	End of pair session
Hook Behavior	Updates or removes if empty	Always removes
Typical Usage	During development	Session cleanup

Testing

The remove functionality includes comprehensive testing:

Unit Tests (7 tests)

• Remove by name matching
• Remove by email matching
• Remove by global alias
• Error handling for non-existent co-authors
• Case-insensitive name matching
• Hook removal when last co-author removed
• Error handling for uninitialized repositories

Integration Tests (5 tests)

• End-to-end removal by name
• End-to-end removal by email
• End-to-end removal by global alias
• Error handling for non-existent co-authors
• Hook management verification

Migration and Compatibility

Backward Compatibility

The remove functionality is fully backward compatible:

• Existing commands continue to work unchanged
• Configuration file format remains the same
• Git hook format is preserved
• Global roster format is unchanged

No Migration Required

Existing git-pair installations can immediately use the remove functionality without any configuration changes or data migration.

Future Enhancements

Potential future improvements to the remove functionality:

Multiple Removal

# Remove multiple co-authors in one command
git pair remove alice bob carol

Pattern Matching

# Remove by domain
git pair remove "*@external-company.com"

# Remove by name pattern
git pair remove "John*"

Interactive Removal

# Interactive mode for selecting co-authors to remove
git pair remove --interactive

Confirmation Prompts

# Add confirmation for destructive operations
git pair remove alice --confirm

Conclusion

The remove co-author functionality significantly enhances git-pair's flexibility for dynamic team collaboration. By providing granular control over co-author management while maintaining the tool's simplicity and reliability, it enables more sophisticated pair and mob programming workflows without sacrificing ease of use.

The feature seamlessly integrates with existing git-pair functionality, maintains backward compatibility, and follows the established patterns for error handling and user experience. With comprehensive testing and intelligent hook management, it provides a robust foundation for flexible team collaboration in Git repositories.