GitInfo 📄

A beautiful command-line tool to fetch and display README files from GitHub repositories with syntax highlighting and rich formatting.

✨ Features

• 🎨 Beautiful Rendering: Markdown rendering with syntax-highlighted code blocks
• 🔍 Flexible Search: Access your own or any public repository
• 🎭 Multiple Themes: Choose from 40+ syntax highlighting themes
• 📊 Repository Info: Display comprehensive repository metadata
• 🔒 Private Repos: Support for private repositories with authentication
• ⚡ Fast: Direct API access without cloning repositories
• 🎯 CLI Ready: Production-ready command-line interface

📋 Table of Contents

• Installation
• Quick Start
• Usage
• Authentication
• Examples
• Available Themes
• API Usage
• Contributing
• License

🚀 Installation

Using pip

pip install PyGithub rich

From source

git clone https://github.com/cumulus13/gitinfo.git
cd gitinfo
pip install -r requirements.txt

Requirements

Create a requirements.txt file:

PyGithub>=2.0.0
rich>=13.0.0

⚡ Quick Start

# View README from any public repository
python gitinfo.py torvalds/linux

# View README from your own repository (requires authentication)
export GITHUB_TOKEN="your_github_token_here"
python gitinfo.py myrepo --own

📖 Usage

Basic Syntax

python gitinfo.py <repository> [options]

Command-Line Options

Option	Short	Description
repository	-	Repository name (username/repo or just repo for own repos)
--token	-t	GitHub Personal Access Token
--own	-	Indicate this is your own repository
--private	-	Indicate this is a private repository
--no-readme	-	Skip displaying README, only show repository info
--no-info	-	Skip displaying repository info, only show README
--theme	-	Syntax highlighting theme (default: monokai)
--verbose	-v	Enable verbose output
--rate-limit	-	Show GitHub API rate limit information
--version	-	Show version information
--help	-h	Show help message

🔐 Authentication

Why Authenticate?

• Access private repositories
• Higher API rate limits (5,000 vs 60 requests/hour)
• Access your own repositories

Getting a GitHub Token

1. Go to GitHub Settings → Developer Settings → Personal Access Tokens
2. Click "Generate new token (classic)"
3. Give it a name and select scopes:
   • repo - Full control of private repositories
   • public_repo - Access public repositories
4. Click "Generate token" and copy it

Using the Token

Method 1: Environment Variable (Recommended)

export GITHUB_TOKEN="ghp_your_token_here"
python gitinfo.py myrepo --own

Method 2: Command-Line Argument

python gitinfo.py myrepo --own --token "ghp_your_token_here"

Method 3: Add to your shell profile

Add to ~/.bashrc or ~/.zshrc:

export GITHUB_TOKEN="ghp_your_token_here"

💡 Examples

View Public Repository README

python gitinfo.py torvalds/linux

View Your Own Repository

python gitinfo.py my-awesome-project --own

View Private Repository

python gitinfo.py my-private-repo --own --private

Custom Syntax Highlighting Theme

python gitinfo.py python/cpython --theme dracula

Show Only README (No Repository Info)

python gitinfo.py microsoft/vscode --no-info

Show Only Repository Info (No README)

python gitinfo.py facebook/react --no-readme

Verbose Mode with Rate Limit Info

python gitinfo.py psf/requests --verbose --rate-limit

Multiple Repositories (Using Shell Loop)

for repo in torvalds/linux python/cpython microsoft/vscode; do
  python gitinfo.py $repo
  echo "---"
done

🎨 Available Themes

The tool supports all Pygments themes. Popular choices include:

• monokai (default) - Dark, vibrant colors
• dracula - Dark theme with purple accents
• github-dark - GitHub's dark theme
• nord - Arctic, north-bluish color palette
• solarized-dark - Popular dark theme
• material - Material Design inspired
• vim - Classic Vim colors
• fruity - Colorful and bright
• native - Similar to VSCode default
• one-dark - Atom's One Dark theme

Try different themes:

python gitinfo.py username/repo --theme <theme-name>

🔧 API Usage

You can also use the tool as a Python library:

from gitinfo import GitHubReadmeFinder

# Initialize
finder = GitHubReadmeFinder(access_token="your_token")

# Find README
detail_repo, readme_content = finder.find_readme(
    "torvalds/linux",
    own=False,
    public=True
)

# Display repository info
finder.display_repo_info(detail_repo)

# Display README with custom theme
if readme_content:
    finder.display_readme(
        readme_content,
        detail_repo['full_name'],
        "README.md",
        theme="dracula"
    )

# Check rate limits
finder.show_rate_limit()

Advanced Usage

from gitinfo import GitHubReadmeFinder
import json

# Initialize with verbose mode
finder = GitHubReadmeFinder(
    access_token="your_token",
    verbose=True
)

# Get multiple repositories
repos = ["python/cpython", "torvalds/linux", "microsoft/vscode"]

for repo_name in repos:
    detail, readme = finder.find_readme(repo_name, own=False)
    
    # Save to file
    if readme:
        filename = f"{repo_name.replace('/', '_')}_README.md"
        with open(filename, 'w') as f:
            f.write(readme)
    
    # Save metadata as JSON
    with open(f"{repo_name.replace('/', '_')}_info.json", 'w') as f:
        json.dump(detail, f, indent=2)

📊 Output Format

Repository Information Table

The tool displays:

• Repository name and full name
• Description
• URL
• Visibility (Public/Private)
• Stars and forks count
• Primary language
• Default branch
• Last commit information

README Display

• Automatic markdown rendering
• Syntax-highlighted code blocks
• Support for .md, .rst, .txt files
• Customizable color themes

🐛 Troubleshooting

"Repository not found or not accessible"

• Check repository name format: username/repo
• Verify repository exists and is public
• For private repos, ensure you have access and provided token

"Authentication required for own repositories"

• Set your GitHub token via GITHUB_TOKEN environment variable
• Or use --token argument

Rate Limit Errors

• Without authentication: 60 requests/hour
• With authentication: 5,000 requests/hour
• Use --rate-limit to check current usage

Module Not Found

pip install PyGithub rich

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

Development Setup

git clone https://github.com/cumulus13/gitinfo.git
cd gitinfo
pip install -r requirements-dev.txt

Running Tests

pytest tests/

📝 License

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

🙏 Acknowledgments

• PyGithub - Python library for GitHub API
• Rich - Beautiful terminal formatting
• Pygments - Syntax highlighting

📧 Contact

cumulus13 - @cumulus13

Project Link: https://github.com/cumulus13/gitinfo

⭐ Star History

If you find this project useful, please consider giving it a star!

---

Made with ❤️ and Python

🙌 Author

Hadi Cahyadi

Support me on Patreon