GitFollow

GitFollow is a powerful CLI tool to track your GitHub followers and unfollows with ease. Get notified when someone follows or unfollows you, generate detailed reports, and automate your follower monitoring with GitHub Actions.

Core Features

• 🔍 Track new followers in real-time
• Detect unfollows automatically
• Generate detailed statistics and reports
• Maintain complete history with timestamps
• Create GitHub Issues automatically on changes
• Local JSON-based storage

Beautiful Output

• Colorized terminal output
• Formatted tables (TTY::Table)
• Progress spinners
• Markdown and plain text reports

Developer-Friendly

• JSON export support
• CSV export for data analysis
• Configurable data directory
• Rate limit aware
• Comprehensive error handling

gem install gitfollow

git clone https://github.com/bulletdev/gitfollow.git
cd gitfollow
bundle install
gem build gitfollow.gemspec
gem install ./gitfollow-0.1.0.gem

GitFollow requires a GitHub Personal Access Token with appropriate permissions.

1. Generate a token: Go to GitHub Settings → Developer settings → Personal access tokens
2. Required scopes: read:user (to read your follower data)
3. Set the token:

export OCTOCAT_TOKEN="your_github_token_here"

Or create a .env file:

OCTOCAT_TOKEN=your_github_token_here

First, initialize GitFollow to create your first snapshot:

gitfollow init

Output:

✔ Fetching initial data... Done!

Initialization complete!
Username: @yourname
Followers: 542
Following: 123
Mutual: 89

Run 'gitfollow check' to detect changes.

Check for new followers or unfollows:

gitfollow check

Output:

✔ Checking for changes... Done!

Changes detected for @yourname

✅ New Followers (2):
  • @newuser1
  • @newuser2

❌ Unfollowed (1):
  • @olduser

Net change: +1
Previous: 542 → Current: 543

View your current follower statistics:

gitfollow stats

Output:

Follower Statistics for @yourname
==================================================
┌──────────────────────┬─────┐
│Followers             │543  │
│Following             │123  │
│Mutual                │89   │
│Ratio                 │4.41 │
│Total New Followers   │15   │
│Total Unfollows       │3    │
└──────────────────────┴─────┘

Last Updated: 2025-10-07 09:00:00 UTC

Generate a detailed report:

# Plain text report
gitfollow report

# Markdown report
gitfollow report --format=markdown

# Save to file
gitfollow report --format=markdown --output=report.md

List users who follow you and whom you follow back:

gitfollow mutual

List users you follow who don't follow you back:

gitfollow non-followers

Export your data for analysis:

# Export to JSON
gitfollow export json data.json

# Export to CSV
gitfollow export csv data.csv

All commands support JSON output:

gitfollow check --json
gitfollow stats --json
gitfollow mutual --json

Display changes in a formatted table:

gitfollow check --table

Suppress output if no changes detected:

gitfollow check --quiet

Store data in a custom location:

gitfollow check --data-dir=/path/to/data

Automatically create an issue when changes are detected:

gitfollow check --notify="bulletdev/gitfollow"

Set up automated daily checks using GitHub Actions:

Create .github/workflows/daily-check.yml:

name: Daily Follower Check

on:
  schedule:
    - cron: '0 9 * * *'  # Run daily at 9 AM UTC
  workflow_dispatch:

jobs:
  check-followers:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'

      - name: Install GitFollow
        run: gem install gitfollow

      - name: Cache data
        uses: actions/cache@v4
        with:
          path: ~/.gitfollow
          key: gitfollow-data

      - name: Check followers
        env:
          OCTOCAT_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          gitfollow init || true
          gitfollow check --notify="${{ github.repository }}"

1. Push the workflow file to your repository
2. Go to Actions tab in your repository
3. Enable the workflow
4. It will run automatically every day!

You can create a .gitfollow.yml config file (optional):

# Custom data directory
data_dir: ~/.gitfollow

# Default notification repository
notify_repo: bulletdev/gitfollow

# Output preferences
output:
  colorize: true
  format: table

GitFollow stores data in ~/.gitfollow/ by default:

~/.gitfollow/
├── snapshots.json  # Follower snapshots
└── history.json    # Change history

git clone https://github.com/bulletdev/gitfollow.git
cd gitfollow
bundle install

bundle exec rspec

bundle exec rubocop

gem build gitfollow.gemspec

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure:

• All tests pass (bundle exec rspec)
• Code follows style guide (bundle exec rubocop)
• Add tests for new features
• Update documentation as needed

# Build the gem
gem build gitfollow.gemspec

# Push to RubyGems
gem push gitfollow-0.1.0.gem

1. Update version in lib/gitfollow/version.rb
2. Update CHANGELOG.md
3. Commit changes
4. Create and push a tag:

git tag v0.1.0
git push origin v0.1.0

The GitHub Actions workflow will automatically build and publish to RubyGems.

Error: Authentication failed while fetching followers

Solution: Ensure your GitHub token is valid and has the required read:user scope.

Error: Rate limit exceeded

Solution: GitHub API has rate limits. Wait for the limit to reset or reduce check frequency.

This is expected! Run gitfollow init first to create your initial snapshot.

• Never commit your GitHub token to version control
• Use GitHub Secrets for CI/CD workflows
• The .env file should be in .gitignore
• Tokens are never logged or stored in data files

This project is licensed under the MIT License - see the LICENSE file for details.

• Built with Octokit for GitHub API
• Uses Thor for CLI framework
• Formatted output with TTY::Table

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation

Made with 💎♦️ by Michael D. Bullet

⭐ Star this repo if you find it useful!