git-seo

Make your Git repositories discoverable.

Overview

Just like web SEO helps pages rank in search engines, Git SEO helps repositories get discovered on GitHub, GitLab, Bitbucket, and across git forges.

git-seo is a CLI tool that:

• Analyzes repository metadata, README quality, and social signals

• Scores discoverability across multiple dimensions

• Recommends actionable improvements

• Compares repositories side-by-side

Installation

# Clone the repository
git clone https://gitlab.com/hyperpolymath/git-seo.git
cd git-seo

# Install dependencies
julia --project=. -e 'using Pkg; Pkg.instantiate()'

# Run directly
julia --project=. bin/git-seo analyze https://github.com/JuliaLang/julia

Using justfile

just setup    # Install dependencies
just build    # Precompile
just run analyze https://github.com/user/repo

Usage

Analyze a Repository

git-seo analyze https://github.com/JuliaLang/julia

Example output:

Git SEO Analysis Report
==================================================
Repository: JuliaLang/julia
Forge: Github

Overall Score: 78.5/100 (78.5%)

Category Scores
--------------------------------------------------
  Metadata     22.0/25.0
  Readme       28.0/30.0
  Social       15.5/20.0
  Activity     10.0/15.0
  Quality       8.0/10.0

Recommendations
--------------------------------------------------
  1. Add more topics/tags (aim for 5-10 relevant keywords)

Compare Repositories

git-seo compare https://github.com/user/repo1 https://github.com/user/repo2

Get Optimization Suggestions

git-seo optimize https://github.com/user/repo

Interactive Fix Application (NEW in v0.3.0)

Apply safe fixes interactively with the --apply flag:

git-seo optimize https://github.com/user/repo --apply

The interactive wizard categorizes fixes by risk level:

• 🟢 SAFE (API-only, reversible): Description updates, topic additions

• 🟡 MEDIUM (file modifications): LICENSE creation, badge injection, section additions (v0.4.0+)

• 🔴 UNSAFE (manual required): README creation from scratch

NEW in v0.4.0: GitLab API support, LICENSE file creation, README badge injection, README section addition

Example session:

Interactive Fix Application
==================================================

Found 3 recommendations:
  🟢 SAFE fixes (API-only, reversible): 2
  🟡 MEDIUM fixes (file modifications): 0
  🔴 UNSAFE fixes (manual required): 1

SAFE FIXES
[1/2] Add repository description

  Current description: (empty)
  Enter new description (50-350 chars, or 'skip'): CLI tool for repository SEO analysis
  Apply this description? [Y/n]: y
  ✓ Description updated successfully

[2/2] Add more topics (aim for 5-10 relevant keywords)

  Current topics (2): julia, cli
  Suggestions: git, seo, optimization
  Enter topics to ADD (comma-separated, or 'skip'): git, seo, github
  Final topics (5): julia, cli, git, seo, github
  Apply these topics? [Y/n]: y
  ✓ Topics updated successfully
  Added: git, seo, github

✓ Applied 2/2 safe fixes

Requirements:

• GITHUB_TOKEN or GITLAB_TOKEN environment variable for API mutations

• Repository owner permissions

GitLab Support (NEW in v0.4.0):

# Analyze GitLab repository
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
git-seo analyze https://gitlab.com/user/project --apply

# See docs/GITLAB-INTEGRATION.md for full details

JSON Output (for CI/CD)

git-seo analyze https://github.com/user/repo --json

Batch Analysis

Analyze multiple repositories from a file:

# Create repo list
cat > repos.txt <<EOF
https://github.com/user/repo1
https://github.com/user/repo2
https://github.com/user/repo3
EOF

# Batch analyze
git-seo batch repos.txt --output results.json

# Custom delay for rate limiting
git-seo batch repos.txt --output results.json --delay 2

Key SEO Factors

Repository Metadata (25 points)

• Name: Descriptive, kebab-case, keyword-rich

• Description: 50-350 characters with primary keywords

• Topics: 5-10 relevant tags

• License: Clear SPDX-identified license

README Quality (30 points)

• Badges (build status, version, downloads)

• Clear one-liner description

• Installation instructions

• Usage examples with code blocks

• Screenshots/GIFs for visual projects

Social Signals (20 points)

• Stars, Forks, Watchers

• Active issue discussions

• Pull request engagement

Activity (15 points)

• Recent updates

• Consistent commit history

• Active maintenance

Code Quality (10 points)

• Primary language detection

• License presence

• Documentation structure

Supported Forges

• ✅ GitHub

• ✅ GitLab

• ✅ Bitbucket

• 🔜 Codeberg

• 🔜 Gitea instances

Environment Variables

Variable	Description
GITHUB_TOKEN	GitHub API token for higher rate limits
GITLAB_TOKEN	GitLab API token (for private repos)
BITBUCKET_TOKEN	Bitbucket API token

Ecosystem Integration

Git-seo integrates with other hyperpolymath tools:

• git-hud: Display SEO scores in unified repository dashboard

• gitbot-fleet: Automated application of safe SEO improvements

• reposystem: Bulk analysis of repository ecosystems

• Hypatia: SEO scores as security/abandonment signals

See Integration Guide for details.

CI/CD Integration

See CI/CD Example for GitHub Actions workflow.

Quick setup:

- name: SEO Quality Gate
  run: |
    git clone https://github.com/hyperpolymath/git-seo.git
    cd git-seo
    julia --project=. -e 'using Pkg; Pkg.instantiate()'
    score=$(julia --project=. bin/git-seo analyze "$REPO_URL" --json | jq '.scores.total')
    if (( $(echo "$score < 60" | bc -l) )); then
      echo "SEO score too low: $score/100"
      exit 1
    fi

Development

# Enter Julia REPL with project
just repl

# Run tests
just test

# Validate RSR compliance
just validate

RSR Compliance

This project follows the Rhodium Standard Repositories framework.

just validate  # Check RSR compliance

Contributing

See CONTRIBUTING.adoc for guidelines.

Quick Contributions

• 📝 Documentation improvements

• 🐛 Bug reports

• 💡 Feature suggestions

• 🧪 Test cases

License

PMPL-1.0-or-later License - see LICENSE.txt

Troubleshooting

API Rate Limits

GitHub: 60 requests/hour without token, 5000 with token

# Set token for higher limits
export GITHUB_TOKEN="ghp_..."
git-seo analyze https://github.com/user/repo

GitLab/Bitbucket: Similar patterns with GITLAB_TOKEN and BITBUCKET_TOKEN

Authentication Errors

Ensure your token has repo:read scope (private repos) or public_repo (public only).

Batch Analysis Timeout

Use --delay flag to add delays between requests:

git-seo batch repos.txt --delay 2  # 2 seconds between requests

Links

• GitHub Repository

• GitLab Mirror

• Integration Guide

• Security Policy

• Code of Conduct

• Governance