gith: Track Human-Generated Content in Git

gith is a friendly Git wrapper that helps developers track and certify human-generated content in their repositories. It provides a seamless way to mark commits as entirely human-created while maintaining full Git compatibility.

Why Use gith?

In an era of AI-assisted development, gith provides essential tools to:

• 🎯 Certify Human Work: Mark commits as entirely human-generated with cryptographic verification
• 🛡️ Protect Your Content: Apply licensing that excludes AI training without explicit permission
• 📋 Maintain Transparency: Keep a clear manifest of human vs AI-assisted contributions
• 🔄 Stay Compatible: Works as a drop-in replacement for Git with full command forwarding

Getting Started

Quick Installation

The fastest way to install gith:

cargo install gith

Basic Usage

# Enable tracking in a repository
gith init-tracking

# Make a human-certified commit
gith commit --human -m "Implement custom algorithm"

# View human-generated content
gith list-human

Key Features

• Drop-in Git replacement: All Git commands work exactly as expected
• Human certification: Flag commits as entirely human-generated
• Automatic licensing: Apply "NO AI TRAINING" license to certified content
• Manifest tracking: Maintain a record of all human-generated contributions
• Team collaboration: Share and verify human content across teams

What's Next?

• Installation: Detailed installation instructions for all platforms
• Quick Start: Get up and running in minutes
• Commands: Complete reference for all gith commands
• Examples: Real-world usage scenarios and workflows
• Best Practices: Guidelines for effective usage
• Licensing: Understanding human-generated content licenses

Ready to start tracking your human-generated content? Check out the Quick Start guide to begin certifying your authentic contributions today!

Installation

This page covers the different methods to install gith on your system.

Method 1: Install from Crates.io (Recommended)

The easiest way to install gith is through Rust's package manager:

cargo install gith

This method ensures you get the latest stable release and automatically handles dependencies.

Method 2: Install from Source

If you want to build from the latest source code or contribute to development:

git clone https://github.com/amrit110/gith.git
cd gith
cargo build --release
sudo cp target/release/gith /usr/local/bin/

Method 3: Download Pre-built Binaries

For systems without Rust installed, you can download pre-built binaries:

1. Visit the GitHub releases page
2. Download the appropriate binary for your platform
3. Extract and place in your PATH

Verification

After installation, verify that gith is working correctly:

gith --version

You should see version information displayed.

Prerequisites

• Git: gith requires Git to be installed and available in your PATH
• Rust (for source installation): Version 1.70 or later if building from source

Troubleshooting Installation

Command Not Found

If you get "command not found" after installation:

# Check if gith is in your PATH
which gith
echo $PATH

# For cargo install, ensure ~/.cargo/bin is in your PATH
export PATH="$HOME/.cargo/bin:$PATH"

Permission Issues

If you encounter permission issues during installation:

# For source installation, use a local directory instead
mkdir -p ~/bin
cp target/release/gith ~/bin/
export PATH="$HOME/bin:$PATH"

Rust Installation

If you don't have Rust installed and want to use Method 1 or 2:

# Install Rust via rustup
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source ~/.cargo/env

Quick Start

This guide will get you up and running with gith in just a few minutes.

Initialize a New Repository with gith Tracking

Create a new repository with gith tracking enabled from the start:

# Create a new repository with gith tracking enabled
mkdir my-project
cd my-project
gith init --gith

# Your repository now has:
# - Standard Git initialization
# - .gith/ directory for tracking metadata
# - human_manifest.json for human-generated content tracking
# - Updated .gitignore with gith-specific entries

Add gith to an Existing Repository

Enable gith tracking in an existing Git repository:

# Navigate to your existing Git repository
cd existing-project

# Enable gith tracking
gith init-tracking

# This creates the necessary gith infrastructure while preserving your Git history

Make Your First Human-Certified Commit

Create content and commit it with human certification:

# Create some content
echo "console.log('Hello, human world!');" > app.js

# Stage the file
gith add app.js

# Create a human-certified commit
gith commit --human -m "Add initial application logic"

# The commit will automatically include:
# Human-Flag: true
# License: HUMAN-GENERATED, NO AI TRAINING

View Your Human-Generated Content

Check what content has been certified as human-generated:

# List all human-flagged commits and files
gith list-human

# Show only commits
gith list-human --commits-only

# Show only files
gith list-human --files-only

Regular Git Commands

All standard Git commands work exactly as expected:

gith add file.txt           # Stage files
gith status                 # Check repository status
gith log --oneline         # View commit history
gith branch feature-xyz    # Create branches
gith push origin main      # Push to remote
gith pull                  # Pull from remote
gith diff                  # View changes

Next Steps

Now that you have gith set up:

1. Learn the commands: Check out the Commands reference
2. See examples: Browse practical examples for common workflows
3. Understand licensing: Read about human-generated content licensing
4. Follow best practices: Review our guidelines for effective usage

Command Reference

This page provides detailed documentation for all gith commands.

Repository Initialization

gith init [OPTIONS] [DIRECTORY]

Initialize a new Git repository (identical to git init).

Options:

• --bare - Create a bare repository
• -b, --initial-branch <BRANCH> - Set initial branch name
• --shared[=<PERMISSIONS>] - Create shared repository
• --gith - Also initialize gith tracking

Examples:

# Standard Git initialization
gith init my-project

# Initialize with gith tracking enabled
gith init --gith my-project

# Create with custom initial branch
gith init -b main --gith my-project

gith init-tracking

Enable gith tracking in an existing Git repository.

What it creates:

• .gith/ directory for metadata storage
• human_manifest.json for tracking human-generated content
• Updates .gitignore to exclude gith metadata from version control
• LICENSE-HUMAN file with human-generated content license

Requirements:

• Must be run inside an existing Git repository
• Repository must have at least one commit

Example:

cd existing-git-repo
gith init-tracking

Committing Changes

gith commit [OPTIONS] -m <MESSAGE>

Create commits with optional human certification.

Key Options:

• --human - Mark commit as entirely human-generated
• -a, --all - Stage all modified files before committing
• --allow-empty - Allow empty commits
• -m, --message <MSG> - Commit message

Standard Git Options: All standard git commit options are supported and forwarded to Git.

Examples:

# Regular commit (forwards to git)
gith commit -m "Fix bug in user authentication"

# Human-certified commit
gith commit --human -m "Implement custom sorting algorithm"

# Stage all changes and commit as human-generated
gith commit -a --human -m "Refactor data processing module"

Human-Certified Commit Format:

When using --human, gith automatically adds these trailers to your commit message:

Human-Flag: true
License: HUMAN-GENERATED, NO AI TRAINING

Content Tracking

gith list-human [OPTIONS]

View all human-flagged commits and files in your repository.

Options:

• --commits-only - Display only human-certified commits
• --files-only - Display only files from human-certified commits

Example Output:

$ gith list-human

Human-Generated Commits:
========================
abc123f - 2024-01-15 14:30:25 - Implement custom sorting algorithm
def456a - 2024-01-14 09:15:10 - Add user authentication system
ghi789b - 2024-01-13 16:45:33 - Create initial project structure

Human-Generated Files:
======================
src/sort.rs (from commit abc123f)
src/auth.rs (from commit def456a)
src/main.rs (from commit ghi789b)
README.md (from commit ghi789b)

Filtering Output:

# Show only commits
gith list-human --commits-only

# Show only files
gith list-human --files-only

Standard Git Commands

All other Git commands work exactly as expected and are forwarded to the system's Git installation:

File Operations

gith add file.txt           # Stage files
gith add .                  # Stage all changes
gith rm file.txt            # Remove files
gith mv old.txt new.txt     # Move/rename files

Repository Status

gith status                 # Check repository status
gith diff                   # View unstaged changes
gith diff --staged          # View staged changes
gith log --oneline         # View commit history

Branching

gith branch                 # List branches
gith branch feature-xyz     # Create new branch
gith checkout main          # Switch branches
gith checkout -b new-feature # Create and switch to new branch
gith merge feature-branch   # Merge branches

Remote Operations

gith remote add origin <url>  # Add remote
gith push origin main         # Push to remote
gith pull                     # Pull from remote
gith fetch                    # Fetch from remote
gith clone <url>              # Clone repository

Advanced Operations

gith rebase main              # Rebase current branch
gith reset --hard HEAD~1      # Reset to previous commit
gith stash                    # Stash changes
gith stash pop                # Apply stashed changes

Command Compatibility

gith is designed as a drop-in replacement for Git:

• Unknown commands are automatically forwarded to the system's git command
• All Git options and flags are preserved and passed through
• Exit codes match Git's behavior exactly
• Output formatting is identical to Git's output

This means you can use gith anywhere you would use git without any changes to your workflow or scripts.

Practical Examples

This page provides real-world examples of how to use gith effectively in different development scenarios.

Scenario 1: Starting a New Project

Complete workflow for initializing a new project with gith tracking:

# Initialize project with gith tracking
mkdir awesome-app
cd awesome-app
gith init --gith

# Create initial files
echo "# Awesome App" > README.md
echo "print('Hello World')" > main.py

# Make human-certified commits
gith add README.md
gith commit --human -m "Add project documentation"

gith add main.py
gith commit --human -m "Implement core application logic"

# View your human-generated content
gith list-human

Expected Output:

Human-Generated Commits:
========================
a1b2c3d - 2024-01-15 14:30:25 - Implement core application logic
e4f5g6h - 2024-01-15 14:25:10 - Add project documentation

Human-Generated Files:
======================
main.py (from commit a1b2c3d)
README.md (from commit e4f5g6h)

Scenario 2: Mixed Development Workflow

Example of working with both human-generated and AI-assisted content:

# Human-generated feature
gith add feature.js
gith commit --human -m "Implement user authentication logic"

# AI-assisted bug fix (regular commit)
gith add bugfix.js
gith commit -m "Fix memory leak in data processing"

# Another human-generated feature
gith add api.js
gith commit --human -m "Design RESTful API endpoints"

# See what's certified as human-generated
gith list-human --commits-only

Output shows only human-certified commits:

Human-Generated Commits:
========================
x9y8z7w - 2024-01-15 16:45:30 - Design RESTful API endpoints
a1b2c3d - 2024-01-15 15:20:15 - Implement user authentication logic

Scenario 3: Team Collaboration

Working in a team environment with gith tracking:

# Clone repository with gith tracking
git clone https://github.com/team/project.git
cd project

# Enable gith tracking if not already enabled
gith init-tracking

# Work on features
gith checkout -b feature/user-profiles
echo "const profiles = {};" > profiles.js
gith add profiles.js
gith commit --human -m "Create user profile management system"

# Push branch
gith push origin feature/user-profiles

# Create pull request through your preferred method
# The human certification will be preserved in the commit history

Scenario 4: Converting Existing Repository

Adding gith tracking to an existing project:

# Navigate to existing repository
cd my-existing-project

# Check current state
git log --oneline -5
git status

# Enable gith tracking
gith init-tracking

# From this point forward, selectively mark human-generated commits
echo "// New human-written function" >> utils.js
gith add utils.js
gith commit --human -m "Add utility function for data validation"

# Regular commits continue as normal
gith commit -m "Update dependencies and fix warnings"

Scenario 5: Large Feature Development

Breaking down a large feature into tracked commits:

# Start feature branch
gith checkout -b feature/payment-system

# Human-designed architecture
touch payment_processor.py
gith add payment_processor.py
gith commit --human -m "Design payment processor architecture"

# Human-implemented core logic
# ... implement core payment logic ...
gith add payment_processor.py
gith commit --human -m "Implement core payment processing logic"

# AI-assisted error handling
# ... add error handling with AI assistance ...
gith add payment_processor.py
gith commit -m "Add comprehensive error handling and validation"

# Human-written tests
touch test_payments.py
# ... write tests manually ...
gith add test_payments.py
gith commit --human -m "Add comprehensive payment processor tests"

# Review what was human-generated in this feature
gith list-human --commits-only

Scenario 6: Code Review and Verification

Using gith during code review process:

# Reviewer checks human-generated content
gith list-human --commits-only

# Review specific human-certified files
gith list-human --files-only

# Check specific commit details
git show abc123f  # Shows commit with human-flag trailer

# Verify licensing is properly applied
cat LICENSE-HUMAN

Scenario 7: Automated Workflow Integration

Using gith in scripts and automation:

#!/bin/bash
# Script to batch-commit human-generated files

for file in src/*.rs; do
    if [[ $file =~ "human_written" ]]; then
        gith add "$file"
        gith commit --human -m "Add human-written module: $(basename $file)"
    fi
done

# Generate report of human-generated content
echo "=== Human-Generated Content Report ===" > human_report.txt
gith list-human >> human_report.txt

Scenario 8: Integration with Conventional Commits

Combining gith with conventional commit standards:

# Human-generated features
gith commit --human -m "feat: implement user authentication system"
gith commit --human -m "feat: add payment processing module"

# AI-assisted fixes
gith commit -m "fix: resolve memory leak in data processing"
gith commit -m "docs: update API documentation with examples"

# Human-designed breaking changes
gith commit --human -m "feat!: redesign API with breaking changes"

Scenario 9: Maintaining Project History

Tracking human contributions over time:

# Generate monthly report
echo "## Human Contributions - $(date +%B\ %Y)" > monthly_report.md
echo "" >> monthly_report.md
gith list-human --commits-only >> monthly_report.md

# Check human contribution ratio
total_commits=$(git rev-list --count HEAD)
human_commits=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)
echo "Human-generated: $human_commits of $total_commits commits"

Scenario 10: Multi-Repository Project

Managing gith across multiple related repositories:

# Setup script for multi-repo project
for repo in frontend backend shared-utils; do
    cd $repo
    gith init-tracking
    echo "Enabled gith tracking in $repo"
    cd ..
done

# Commit human-generated shared utilities
cd shared-utils
gith add validation.js
gith commit --human -m "Create shared validation utilities"
cd ..

# Use in other repositories
cd frontend
# ... implement using shared utils ...
gith commit -m "Integrate shared validation utilities"

These examples demonstrate how gith integrates seamlessly into various development workflows while providing clear tracking of human-generated content.

Human-Generated Content License

When you use the --human flag with gith commit, your content is automatically protected with a specialized license designed for human-generated content.

What the License Provides

The human-generated content license automatically:

• ✅ Certifies content as entirely human-generated
• 🚫 Prohibits AI training use without explicit permission
• 📄 Enables redistribution with license preservation
• 🔍 Provides verification through gith's tracking system

License Text

The complete license is automatically created in your repository as LICENSE-HUMAN:

HUMAN-GENERATED CONTENT LICENSE

This content was created entirely by humans without AI assistance.

PERMITTED:
- Use, copy, modify, distribute for any purpose
- Commercial and non-commercial use

PROHIBITED:
- Training AI models without explicit written permission
- Claiming AI generated this content

REQUIRED:
- Preserve this license notice in redistributions
- Maintain human-generation certification

How It Works

Automatic Application

When you run gith commit --human, the license is applied through:

1. Commit Trailers: Added to your commit message

   Human-Flag: true
   License: HUMAN-GENERATED, NO AI TRAINING
   

2. License File: LICENSE-HUMAN created in repository root

3. Manifest Tracking: Recorded in .gith/human_manifest.json

Legal Framework

The license provides:

• Clear Intent: Explicitly states human-only generation
• Permission Scope: Defines what users can and cannot do
• AI Training Protection: Specifically prohibits training use
• Redistribution Requirements: Ensures license preservation

Practical Implications

For Developers

What you can do:

• Use licensed content in any project (commercial or non-commercial)
• Modify and redistribute with proper attribution
• Build upon human-generated components

What you must do:

• Preserve license notices when redistributing
• Maintain certification of human generation
• Respect the original license terms

For AI Companies

Explicitly prohibited:

• Training models on human-certified content without permission
• Scraping repositories for training data that includes licensed content
• Using certified human content in datasets

To obtain permission:

• Contact repository owners directly
• Negotiate explicit written agreements
• Respect developer intent regarding AI training

Customization

Custom License Text

You can customize the license by editing LICENSE-HUMAN after running gith init-tracking:

# Initialize with default license
gith init-tracking

# Customize the license text
nano LICENSE-HUMAN

# Future commits will reference your custom license
gith commit --human -m "First commit with custom license"

Project-Specific Terms

Add project-specific licensing terms:

# Add additional terms to LICENSE-HUMAN
cat >> LICENSE-HUMAN << 'EOF'

ADDITIONAL TERMS:
- Attribution required in derivative works
- Commercial use requires notification to authors
- Research use permitted with citation
EOF

Integration Examples

In README Files

Document your licensing approach:

## Human-Generated Content

This project uses `gith` to track and license human-generated content.

- View certified human contributions: `gith list-human`
- Licensed under HUMAN-GENERATED CONTENT LICENSE
- See LICENSE-HUMAN for full terms

In Contributing Guidelines

Set expectations for contributors:

## Contributing

When contributing original work:
- Use `gith commit --human` for human-generated content
- Regular commits for AI-assisted work are welcome
- All human-certified content falls under our human-generation license

Legal Considerations

Enforceability

The license provides:

• Clear Notice: Explicit human-generation claims
• Specific Prohibitions: Targeted at AI training use
• Standard Terms: Based on established licensing patterns

Compliance

To respect licensed content:

• Check for gith tracking in repositories you use
• Honor license terms when redistributing
• Seek permission for AI training use
• Maintain attributions in derivative works

Liability

The license includes standard disclaimers:

• Content provided "as is"
• No warranty of fitness for purpose
• Limited liability for use

Frequently Asked Questions

Can I change the license after committing?

The license is embedded in commit history and should not be changed retroactively. You can:

• Customize future commits by editing LICENSE-HUMAN
• Add clarifying documentation
• Contact legal counsel for significant changes

Does this affect standard software licenses?

No. The human-generation license works alongside:

• MIT, Apache, GPL licenses for code
• Creative Commons for documentation
• Project-specific licenses

What about collaborative contributions?

For team contributions:

• Each contributor certifies their own content
• Mixed commits can include multiple certifications
• Team policies should define human-generation standards

How does this relate to copyright?

• Copyright remains with original authors
• License grants permissions for use and redistribution
• Human certification adds additional protections
• Standard copyright law still applies

Verification and Compliance

Verifying Human-Generated Content

# Check if repository uses gith
ls -la .gith/

# View human-certified commits
gith list-human --commits-only

# Examine commit details
git show --show-signature <commit-hash>

Compliance Scanning

For automated compliance checking:

#!/bin/bash
# Check for human-generated content licensing
if [ -f "LICENSE-HUMAN" ]; then
    echo "Repository contains human-generated content license"
    gith list-human --commits-only | wc -l | xargs echo "Human commits:"
else
    echo "No human-generation licensing detected"
fi

The human-generated content license provides a clear, enforceable framework for protecting authentic human contributions in the age of AI-assisted development.

Best Practices

This guide outlines recommended practices for using gith effectively in your development workflow.

When to Use Human Certification

✅ Appropriate Use Cases

Use gith commit --human for content that is genuinely created without AI assistance:

# ✅ Good - You wrote this logic yourself
gith commit --human -m "Implement binary search algorithm"

# ✅ Good - Original architectural decisions
gith commit --human -m "Design database schema for user management"

# ✅ Good - Hand-crafted business logic
gith commit --human -m "Add payment processing workflow"

❌ Inappropriate Use Cases

Avoid flagging AI-assisted work as human-generated:

# ❌ Avoid - Don't flag AI-assisted work as human
gith commit --human -m "Add code generated by ChatGPT"

# ❌ Avoid - Mixed human/AI content
gith commit --human -m "Refactor with AI suggestions"

# ❌ Avoid - Uncertainty about origin
gith commit --human -m "Update code (not sure if I used AI)"

Establishing Team Conventions

Define Clear Policies

Create team-wide standards for human certification:

# Example team policy documented in project
cat >> CONTRIBUTING.md << 'EOF'
## Human-Generated Content Policy

- **Core business logic**: Always human-flagged
- **Security-sensitive code**: Human-flagged when possible
- **Bug fixes**: Human-flagged if significant algorithmic changes
- **Documentation**: Mixed (flag original content as human)
- **Tests**: Mixed (flag hand-written test logic as human)
- **Configuration**: Regular commits unless custom logic involved

To view certified human content: `gith list-human`
EOF

Consistent Workflow

Establish predictable patterns:

# Consistent approach for feature development
gith checkout -b feature/user-auth

# 1. Design phase (human)
gith commit --human -m "feat: design authentication architecture"

# 2. Implementation (mixed - be honest)
gith commit --human -m "feat: implement JWT token validation"
gith commit -m "feat: add error handling with AI assistance"

# 3. Testing (mixed)
gith commit --human -m "test: add comprehensive auth tests"
gith commit -m "test: add edge cases from AI suggestions"

Documentation Standards

Project-Level Documentation

Document your human-generation policy:

echo "## Human-Generated Content Policy

This project uses gith to track human-generated content.

### Our Standards
- Original algorithms and business logic: Human-flagged
- Architectural decisions: Human-flagged
- Security implementations: Human-flagged when possible
- Bug fixes: Case-by-case basis
- Generated code: Never human-flagged
- Boilerplate: Regular commits

### Verification
- View certified content: \`gith list-human\`
- Monthly reports generated automatically
- Code review includes human-generation verification

### Questions?
Contact the maintainers for clarification on certification standards.
" >> README.md

gith add README.md
gith commit --human -m "docs: add human-generation policy"

Commit Message Standards

Use clear, descriptive commit messages:

# ✅ Good - Clear about human contribution
gith commit --human -m "implement custom caching algorithm for user sessions"

# ✅ Good - Specific about what's human-generated
gith commit --human -m "design API endpoint structure for payment processing"

# ❌ Avoid - Vague about content
gith commit --human -m "update stuff"

# ❌ Avoid - Unclear about generation method
gith commit --human -m "fix things"

Code Review Integration

Review Process

Include human-generation verification in code reviews:

# Reviewer checklist
echo "## Code Review Checklist

### Human-Generation Verification
- [ ] Human-flagged commits contain genuinely human-generated content
- [ ] No AI-assisted work incorrectly flagged as human
- [ ] Commit messages accurately describe contribution type
- [ ] License implications understood and appropriate

### Technical Review
- [ ] Code quality meets standards
- [ ] Tests included and passing
- [ ] Documentation updated
- [ ] No security vulnerabilities

Use: \`gith list-human --commits-only\` to review human-certified changes
" > .github/pull_request_template.md

Verification Commands

Use these commands during review:

# Review human-certified commits in PR
git log --grep="Human-Flag: true" origin/main..HEAD

# Check specific commit details
git show --show-signature <commit-hash>

# View all human content in branch
gith list-human --commits-only

Security Considerations

Sensitive Code

Be especially careful with security-related code:

# Security implementations should be human when possible
gith commit --human -m "implement password hashing with bcrypt"
gith commit --human -m "add JWT signature verification"

# But be honest about AI assistance
gith commit -m "add rate limiting with AI-suggested parameters"

Access Control

Consider who can make human-certified commits:

# Example pre-commit hook for verification
cat > .git/hooks/pre-commit << 'EOF'
#!/bin/bash
if git log -1 --pretty=%B | grep -q "Human-Flag: true"; then
    echo "⚠️  Human-certified commit detected"
    echo "Please verify this content is entirely human-generated"
    echo "Continue? (y/n)"
    read -r response
    if [[ ! "$response" =~ ^[Yy]$ ]]; then
        exit 1
    fi
fi
EOF
chmod +x .git/hooks/pre-commit

Workflow Integration

Development Branches

Organize branches with human-generation in mind:

# Feature development
gith checkout -b feature/payment-system

# Separate human-designed architecture
gith commit --human -m "design: payment system architecture"

# Implement with mixed approaches
gith commit --human -m "implement: core payment processing logic"
gith commit -m "implement: error handling and validation"

# Separate branch for generated code if needed
gith checkout -b feature/payment-system-generated
# ... add AI-generated boilerplate ...
gith commit -m "add: payment service boilerplate"

Continuous Integration

Integrate verification into CI/CD:

# .github/workflows/verify-human.yml
name: Verify Human Content
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install gith
        run: cargo install gith
      - name: Report human content
        run: |
          echo "## Human-Certified Content in PR" >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
          gith list-human --commits-only | head -10 >> $GITHUB_STEP_SUMMARY
          echo "\`\`\`" >> $GITHUB_STEP_SUMMARY

Maintenance and Monitoring

Regular Audits

Periodically review human-generation patterns:

# Monthly human content report
cat > scripts/human_report.sh << 'EOF'
#!/bin/bash
echo "=== Human Content Report - $(date +%B\ %Y) ==="
echo ""

total_commits=$(git rev-list --count HEAD)
human_commits=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)

echo "Statistics:"
echo "- Total commits: $total_commits"
echo "- Human-certified: $human_commits"
echo "- Percentage: $(( human_commits * 100 / total_commits ))%"
echo ""

echo "Recent human-certified commits:"
gith list-human --commits-only | head -10
EOF

chmod +x scripts/human_report.sh

Quality Assurance

Monitor for inconsistencies:

# Check for potential issues
cat > scripts/audit_human.sh << 'EOF'
#!/bin/bash
echo "Checking for potential human-generation inconsistencies..."

# Look for AI-related keywords in human-flagged commits
git log --grep="Human-Flag: true" --pretty=format:"%h %s" | \
    grep -i -E "(chatgpt|copilot|ai|generated|gpt)" && \
    echo "⚠️  Found AI-related terms in human-flagged commits"

# Check for very short intervals between human commits
git log --grep="Human-Flag: true" --pretty=format:"%h %at %s" | \
    sort -k2 -n | \
    awk '{
        if (prev && ($2 - prev) < 60) {
            print "⚠️  Rapid human commits: " prev_hash " and " $1
        }
        prev = $2; prev_hash = $1
    }'
EOF

chmod +x scripts/audit_human.sh

Common Pitfalls to Avoid

Over-Certification

Don't flag everything as human:

# ❌ Bad - Over-flagging trivial changes
gith commit --human -m "fix typo in comment"
gith commit --human -m "update dependency version"

# ✅ Good - Reserve for meaningful human contributions
gith commit -m "fix typo in comment"
gith commit --human -m "refactor core algorithm for better performance"

Under-Certification

Don't miss significant human contributions:

# ❌ Bad - Missing human contribution
gith commit -m "implement advanced search algorithm"  # Should be --human

# ✅ Good - Proper certification
gith commit --human -m "implement advanced search algorithm"

Inconsistent Standards

Maintain consistent certification criteria:

# Document decisions for consistency
echo "# Human Certification Decisions Log

## 2024-01-15
- Decision: All custom algorithms flagged as human
- Decision: Configuration files are regular commits unless custom logic
- Decision: Generated migrations are regular commits

## 2024-01-20
- Decision: Security implementations prioritized for human flagging
- Decision: Test utilities can be mixed based on complexity
" > docs/certification_log.md

Following these best practices ensures that your use of gith provides accurate, consistent, and valuable tracking of human-generated content in your projects.

Integration with CI/CD and Tooling

This page covers how to integrate gith with various development tools, CI/CD systems, and workflows.

GitHub Actions

Basic Verification Workflow

Create .github/workflows/verify-human-content.yml:

name: Verify Human Content
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Need full history for gith
      - name: Install Rust
        uses: actions-rs/toolchain@v1
        with:
          toolchain: stable
      - name: Install gith
        run: cargo install gith
      - name: Verify human content tracking
        run: |
          if [ -d ".gith" ]; then
            gith list-human --commits-only
            echo "✅ Human-certified commits verified"
          else
            echo "ℹ️  No gith tracking in this repository"
          fi

PR Reporting

Add human content reports to pull requests:

name: Human Content Report
on: pull_request

jobs:
  report:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install gith
        run: cargo install gith
      - name: Generate human content report
        run: |
          if [ -d ".gith" ]; then
            echo "## Human-Certified Content in PR" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "### Commits" >> $GITHUB_STEP_SUMMARY
            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
            gith list-human --commits-only | head -10 >> $GITHUB_STEP_SUMMARY
            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
            echo "" >> $GITHUB_STEP_SUMMARY
            echo "### Files" >> $GITHUB_STEP_SUMMARY
            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
            gith list-human --files-only | head -20 >> $GITHUB_STEP_SUMMARY
            echo "\`\`\`" >> $GITHUB_STEP_SUMMARY
          fi

Release Automation

Include human content in release notes:

name: Create Release
on:
  push:
    tags: ['v*']

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install gith
        run: cargo install gith
      - name: Generate release notes
        run: |
          echo "## Human-Generated Content" > release_notes.md
          echo "" >> release_notes.md
          if [ -d ".gith" ]; then
            human_commits=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)
            total_commits=$(git rev-list --count HEAD)
            echo "- Human-certified commits: $human_commits of $total_commits" >> release_notes.md
            echo "- Percentage human-generated: $(( human_commits * 100 / total_commits ))%" >> release_notes.md
          fi
      - name: Create Release
        uses: actions/create-release@v1
        with:
          tag_name: ${{ github.ref }}
          release_name: Release ${{ github.ref }}
          body_path: release_notes.md

GitLab CI

Basic Pipeline

Create .gitlab-ci.yml:

stages:
  - verify
  - report

verify-human-content:
  stage: verify
  image: rust:latest
  before_script:
    - cargo install gith
  script:
    - |
      if [ -d ".gith" ]; then
        echo "Verifying human-certified content..."
        gith list-human --commits-only
        echo "✅ Verification complete"
      else
        echo "ℹ️  No gith tracking detected"
      fi
  only:
    - merge_requests
    - main

human-content-report:
  stage: report
  image: rust:latest
  before_script:
    - cargo install gith
  script:
    - |
      if [ -d ".gith" ]; then
        echo "## Human Content Report" > report.md
        echo "" >> report.md
        total=$(git rev-list --count HEAD)
        human=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)
        echo "- Total commits: $total" >> report.md
        echo "- Human-certified: $human" >> report.md
        echo "- Percentage: $(( human * 100 / total ))%" >> report.md
        cat report.md
      fi
  artifacts:
    reports:
      junit: report.md
  only:
    - main

Pre-commit Hooks

Installation and Setup

Install pre-commit and configure for gith:

# Install pre-commit
pip install pre-commit

# Create .pre-commit-config.yaml
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: local
    hooks:
      - id: gith-human-reminder
        name: Remind about human certification
        entry: scripts/pre-commit-gith.sh
        language: script
        stages: [pre-commit]
        always_run: true
EOF

# Create the hook script
mkdir -p scripts
cat > scripts/pre-commit-gith.sh << 'EOF'
#!/bin/bash
echo "💡 Tip: Use 'gith commit --human' to certify human-generated content"

if [ -d ".gith" ]; then
    echo "Recent human-certified commits:"
    gith list-human --commits-only | head -3
fi
echo ""
EOF

chmod +x scripts/pre-commit-gith.sh

# Install hooks
pre-commit install

Advanced Pre-commit Hook

More sophisticated verification:

cat > scripts/advanced-gith-hook.sh << 'EOF'
#!/bin/bash

# Check if commit message indicates human generation
if git log -1 --pretty=%B | grep -q "\--human"; then
    echo "⚠️  Detected --human flag in commit message"
    echo "Make sure to use: gith commit --human -m 'message'"
    echo "Instead of: git commit -m 'message --human'"
    exit 1
fi

# Remind about human certification for significant changes
lines_changed=$(git diff --cached --numstat | awk '{sum += $1 + $2} END {print sum}')
if [ "$lines_changed" -gt 50 ]; then
    echo "📊 Large changeset detected ($lines_changed lines)"
    echo "💡 Consider using 'gith commit --human' if this is human-generated"
fi

# Check for AI-related keywords in staged files
if git diff --cached --name-only | xargs grep -l -i -E "(chatgpt|copilot|ai.generated|gpt-)" 2>/dev/null; then
    echo "🤖 Detected AI-related keywords in staged files"
    echo "💡 Consider regular commit unless content is entirely human-generated"
fi
EOF

chmod +x scripts/advanced-gith-hook.sh

IDE Integration

VS Code Settings

Create .vscode/settings.json for gith integration:

{
  "git.defaultCloneDirectory": "./projects",
  "git.confirmSync": false,
  "git.enableSmartCommit": true,
  "terminal.integrated.env.linux": {
    "GITH_DEFAULT_HUMAN": "false"
  },
  "terminal.integrated.env.osx": {
    "GITH_DEFAULT_HUMAN": "false"
  },
  "terminal.integrated.env.windows": {
    "GITH_DEFAULT_HUMAN": "false"
  }
}

VS Code Tasks

Create .vscode/tasks.json:

{
    "version": "2.0.0",
    "tasks": [
        {
            "label": "List Human Content",
            "type": "shell",
            "command": "gith list-human",
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared"
            }
        },
        {
            "label": "Human Commit",
            "type": "shell",
            "command": "gith commit --human -m '${input:commitMessage}'",
            "group": "build",
            "presentation": {
                "echo": true,
                "reveal": "always",
                "focus": false,
                "panel": "shared"
            }
        }
    ],
    "inputs": [
        {
            "id": "commitMessage",
            "description": "Commit message",
            "default": "Update human-generated content",
            "type": "promptString"
        }
    ]
}

Docker Integration

Development Container

Create .devcontainer/devcontainer.json:

{
    "name": "Gith Development",
    "image": "rust:latest",
    "postCreateCommand": "cargo install gith",
    "customizations": {
        "vscode": {
            "extensions": [
                "rust-lang.rust-analyzer"
            ]
        }
    },
    "forwardPorts": [3000],
    "features": {
        "ghcr.io/devcontainers/features/git:1": {}
    }
}

CI Docker Image

Create a custom image with gith pre-installed:

# Dockerfile.gith-ci
FROM rust:slim

RUN apt-get update && apt-get install -y \
    git \
    pkg-config \
    libssl-dev \
    && rm -rf /var/lib/apt/lists/*

RUN cargo install gith

COPY scripts/ci-verify.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/ci-verify.sh

ENTRYPOINT ["/usr/local/bin/ci-verify.sh"]

# scripts/ci-verify.sh
#!/bin/bash
set -e

echo "🔍 Verifying gith repository..."

if [ ! -d ".gith" ]; then
    echo "ℹ️  No gith tracking detected"
    exit 0
fi

echo "📊 Human content statistics:"
total_commits=$(git rev-list --count HEAD)
human_commits=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)

echo "- Total commits: $total_commits"
echo "- Human-certified: $human_commits"
echo "- Percentage: $(( human_commits * 100 / total_commits ))%"

echo ""
echo "📝 Recent human-certified commits:"
gith list-human --commits-only | head -5

echo "✅ Verification complete"

Monitoring and Analytics

Prometheus Metrics

Create a metrics exporter:

# scripts/gith-metrics.sh
#!/bin/bash

# Export metrics in Prometheus format
cat << EOF
# HELP gith_total_commits Total number of commits in repository
# TYPE gith_total_commits counter
gith_total_commits $(git rev-list --count HEAD)

# HELP gith_human_commits Number of human-certified commits
# TYPE gith_human_commits counter
gith_human_commits $(gith list-human --commits-only 2>/dev/null | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)

# HELP gith_human_files Number of files in human-certified commits
# TYPE gith_human_files counter
gith_human_files $(gith list-human --files-only 2>/dev/null | grep -v "Human-Generated Files" | grep -v "=" | wc -l)

# HELP gith_tracking_enabled Whether gith tracking is enabled (1 or 0)
# TYPE gith_tracking_enabled gauge
gith_tracking_enabled $([ -d ".gith" ] && echo 1 || echo 0)
EOF

Weekly Reports

Automated reporting script:

# scripts/weekly-report.sh
#!/bin/bash

REPORT_FILE="reports/weekly-$(date +%Y-%U).md"
mkdir -p reports

cat > "$REPORT_FILE" << EOF
# Weekly Human Content Report
## Week $(date +%U), $(date +%Y)

### Summary
EOF

if [ -d ".gith" ]; then
    total=$(git rev-list --count HEAD)
    human=$(gith list-human --commits-only | grep -v "Human-Generated Commits" | grep -v "=" | wc -l)

    cat >> "$REPORT_FILE" << EOF
- Total commits: $total
- Human-certified: $human
- Human percentage: $(( human * 100 / total ))%

### Recent Human Commits
\`\`\`
$(gith list-human --commits-only | head -10)
\`\`\`

### Human-Generated Files
\`\`\`
$(gith list-human --files-only | head -20)
\`\`\`
EOF
else
    echo "- No gith tracking enabled" >> "$REPORT_FILE"
fi

echo "📊 Report generated: $REPORT_FILE"

These integration examples help you incorporate gith into your existing development and deployment workflows, providing automated verification and reporting of human-generated content.

Troubleshooting

This page covers common issues you might encounter when using gith and their solutions.

Installation Issues

Command Not Found

Problem: gith: command not found after installation

Solutions:

# Check if gith is installed and in PATH
which gith
echo $PATH

# For cargo install, ensure ~/.cargo/bin is in PATH
export PATH="$HOME/.cargo/bin:$PATH"
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Verify installation
gith --version

Permission Denied

Problem: Permission issues during source installation

Solution:

# Use local installation instead of system-wide
mkdir -p ~/bin
cp target/release/gith ~/bin/
export PATH="$HOME/bin:$PATH"

# Or use cargo install (recommended)
cargo install gith

Build Failures

Problem: Compilation errors when building from source

Solutions:

# Update Rust toolchain
rustup update stable
rustup default stable

# Clean and rebuild
cargo clean
cargo build --release

# Check system dependencies (Linux)
sudo apt update
sudo apt install build-essential pkg-config libssl-dev

# Check system dependencies (macOS)
xcode-select --install

Repository Setup Issues

Not a Git Repository

Problem: gith init-tracking fails with "not a git repository"

Solution:

# Ensure you're in a Git repository
git status

# If not initialized, initialize first
git init
git add .
git commit -m "Initial commit"

# Then enable gith tracking
gith init-tracking

Tracking Already Enabled

Problem: gith init-tracking reports tracking already enabled

Solution:

# Check if .gith directory exists
ls -la .gith/

# If corrupted, reinitialize (safe - preserves Git history)
rm -rf .gith/
gith init-tracking

# Verify tracking is working
gith list-human

Permission Issues with .gith Directory

Problem: Cannot write to .gith directory

Solution:

# Check directory permissions
ls -la .gith/

# Fix permissions
chmod 755 .gith/
chmod 644 .gith/human_manifest.json

# If still issues, recreate
sudo rm -rf .gith/
gith init-tracking

Command Issues

Human Flag Not Working

Problem: --human flag not adding trailers to commits

Diagnostic Steps:

# Check if gith tracking is enabled
ls -la .gith/

# Verify commit was made with gith (not git)
git log -1 --pretty=format:"%B"

# Check for human-flag trailer
git log -1 --grep="Human-Flag: true"

Solutions:

# Ensure using gith command
gith commit --human -m "message"  # ✅ Correct
git commit --human -m "message"   # ❌ Wrong - no human flag

# Check if tracking is initialized
gith init-tracking

# Verify with test commit
echo "test" > test.txt
gith add test.txt
gith commit --human -m "test human commit"
git log -1 --pretty=format:"%B"

Commands Not Forwarding to Git

Problem: Standard Git commands fail when using gith

Diagnostic Steps:

# Check if git is in PATH
which git

# Test git directly
git status

# Test gith forwarding
gith status

Solutions:

# Ensure git is installed and accessible
git --version

# Check PATH includes git location
echo $PATH

# If git not found, install or fix PATH
# Ubuntu/Debian:
sudo apt install git

# macOS:
xcode-select --install
# or
brew install git

Manifest Corruption

Problem: Human manifest appears corrupted or empty

Symptoms:

# Empty or malformed output
gith list-human
# Shows no content despite human commits

Solutions:

# Check manifest file
cat .gith/human_manifest.json

# Verify JSON is valid
python -m json.tool .gith/human_manifest.json

# If corrupted, recreate (loses tracking history)
rm .gith/human_manifest.json
gith init-tracking

# Alternative: Manual repair
echo '{"commits": {}, "files": {}}' > .gith/human_manifest.json

Performance Issues

Slow Operations

Problem: gith commands are significantly slower than git

Diagnostic Steps:

# Time comparison
time git status
time gith status

# Check repository size
git count-objects -vH

# Check manifest size
ls -lh .gith/human_manifest.json

Solutions:

# For very large repositories, consider selective tracking
# Clean up manifest if it's grown too large
cp .gith/human_manifest.json .gith/human_manifest.json.backup
echo '{"commits": {}, "files": {}}' > .gith/human_manifest.json

# For large files, check .gitignore includes .gith/
echo ".gith/" >> .gitignore

Integration Issues

CI/CD Failures

Problem: Build pipelines fail when using gith

Common Issues and Solutions:

# Issue: gith not available in CI
# Solution: Install in CI pipeline
- name: Install gith
  run: cargo install gith

# Issue: Git history not available
# Solution: Fetch full history
- uses: actions/checkout@v4
  with:
    fetch-depth: 0

# Issue: Permission problems
# Solution: Use appropriate runner
jobs:
  test:
    runs-on: ubuntu-latest  # Ensure compatible OS

Pre-commit Hook Failures

Problem: Pre-commit hooks fail with gith

Solution:

# Check hook configuration
cat .git/hooks/pre-commit

# Ensure gith is available in hook environment
#!/bin/bash
export PATH="$HOME/.cargo/bin:$PATH"
which gith || { echo "gith not found"; exit 1; }

# Test hook manually
.git/hooks/pre-commit

Data Recovery

Lost Human Certifications

Problem: Human-flagged commits not showing in gith list-human

Recovery Steps:

# Search for human-flagged commits in history
git log --grep="Human-Flag: true" --oneline

# Rebuild manifest from commit history
cat > rebuild_manifest.sh << 'EOF'
#!/bin/bash
echo '{"commits": {}, "files": {}}' > .gith/human_manifest.json

git log --grep="Human-Flag: true" --pretty=format:"%H %ct %s" | while read hash timestamp message; do
    # This would need to be implemented properly
    echo "Found human commit: $hash"
done
EOF

Corrupted Repository

Problem: .gith directory or tracking completely broken

Solution:

# Complete reset (preserves Git history, loses gith tracking history)
rm -rf .gith/
gith init-tracking

# Verify basic functionality
echo "test" > test.txt
gith add test.txt
gith commit --human -m "test commit after reset"
gith list-human

Getting Help

Debug Information

When reporting issues, include this information:

# System information
uname -a
echo "Git version: $(git --version)"
echo "Gith version: $(gith --version)"
echo "Rust version: $(rustc --version)"

# Repository state
echo "Git status:"
git status --porcelain
echo "Gith directory:"
ls -la .gith/ 2>/dev/null || echo "No .gith directory"

# Recent commits
echo "Recent commits:"
git log --oneline -5

# Human commits
echo "Human commits:"
gith list-human --commits-only 2>&1

Common Error Messages

Error: error: failed to execute git

Solution:

# Ensure git is installed and in PATH
which git
git --version

Error: IO error: Permission denied

Solution:

# Check file permissions
ls -la .gith/
# Fix permissions
chmod -R 755 .gith/

Error: JSON parse error in manifest

Solution:

# Reset manifest
echo '{"commits": {}, "files": {}}' > .gith/human_manifest.json

Support Resources

• Documentation: This guide and inline help (gith --help)
• Issues: GitHub Issues
• Discussions: GitHub Discussions

When reporting issues, please include:

1. Full error message
2. Steps to reproduce
3. System information (from debug section above)
4. Expected vs actual behavior