GitFollow

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

• Track new followers and detect unfollows automatically
• Generate detailed statistics and reports (text and Markdown)
• Create GitHub Issues automatically on changes, with a 7-day activity summary
• Complete history with timestamps stored locally in JSON
• JSON and CSV export support
• Colorized terminal output with formatted tables

gem install gitfollow

Or from source:

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

GitFollow requires a GitHub Personal Access Token with read:user scope.

1. Generate a token at GitHub Settings -> Developer settings -> Personal access tokens
2. Set it as an environment variable:

export OCTOCAT_TOKEN="your_github_token_here"

Or create a .env file:

OCTOCAT_TOKEN=your_github_token_here

Create your first snapshot:

gitfollow init

Fetching initial data... Done!

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

Run 'gitfollow check' to detect changes.

gitfollow check

Checking for changes... Done!

Changes detected for @yourname

+ New Followers (2):
  * @newuser1
  * @newuser2

- Unfollowed (1):
  * @olduser

Net change: +1
Previous: 542 -> Current: 543

gitfollow stats

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

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

gitfollow report
gitfollow report --format=markdown
gitfollow report --format=markdown --output=report.md

GitFollow Report for @yourname
==================================================

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

Statistics:
  Followers:         543
  Following:         123
  Mutual:             89
  Ratio:            4.41
  Total New:          15
  Total Unfollows:     3

Recent Activity:
--------------------------------------------------
  [2026-10-07 09:00] NEW @newuser1
  [2026-10-06 09:00] UNFOLLOW @olduser

gitfollow mutual
gitfollow non-followers

gitfollow export json data.json
gitfollow export csv data.csv

gitfollow check --json          # JSON output
gitfollow check --table         # table format
gitfollow check --quiet         # suppress output if no changes
gitfollow check --data-dir=/path/to/data
gitfollow check --notify="owner/repo"   # create a GitHub Issue on changes

1. Add your token as a repository secret named OCTOCAT_TOKEN
2. Create .github/workflows/daily-check.yml:

name: Daily Follower Check

on:
  schedule:
    - cron: '0 9 * * *'
  workflow_dispatch:

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

      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.4.5'
          bundler-cache: true

      - name: Install GitFollow
        run: |
          gem build gitfollow.gemspec
          gem install ./gitfollow-*.gem

      - name: Cache follower data
        uses: actions/cache@v4
        with:
          path: ~/.gitfollow
          key: gitfollow-data-${{ github.repository_owner }}-${{ github.run_id }}
          restore-keys: |
            gitfollow-data-${{ github.repository_owner }}-

      - name: Initialize if first run
        env:
          OCTOCAT_TOKEN: ${{ secrets.OCTOCAT_TOKEN }}
        run: |
          if [ ! -f ~/.gitfollow/snapshots.json ]; then
            gitfollow init
          fi

      - name: Check for changes
        env:
          OCTOCAT_TOKEN: ${{ secrets.OCTOCAT_TOKEN }}
          REPO: ${{ github.repository }}
        run: gitfollow check --notify="$REPO" --quiet

When changes are detected, GitFollow creates a GitHub Issue with:

• Today's diff: new followers and unfollows since the last run
• Summary: previous/current count and net change
• Last 7 days activity: full table of recent events

Data is stored in ~/.gitfollow/ by default:

~/.gitfollow/
├── snapshots.json  # follower snapshots
└── history.json    # change history

Use --data-dir to change the location.

bundle install
bundle exec rspec       # run tests
bundle exec rubocop     # lint
gem build gitfollow.gemspec

1. Fork the repository
2. Create a feature branch
3. Commit your changes with tests
4. Open a Pull Request

• Never commit your GitHub token to version control
• Use GitHub Secrets for CI/CD workflows
• Keep .env in .gitignore

MIT — see LICENSE.

Made with Ruby by Michael D. Bullet