🐙 GitHub User Activity CLI

A sleek, lightweight command-line tool built with Python to fetch and display GitHub user activity. Track any GitHub user's recent public activities with a simple command.

✨ Features

• Simple & Fast: Fetch user activity with a single command
• Comprehensive Activity Tracking: Displays pushes, issues, pull requests, forks, stars, and more
• File Export: Save activity data to a text file for later reference
• Error Handling: Robust input validation and helpful error messages
• Real-time Data: Fetches live data from GitHub API
• Multiple Event Types: Supports 12+ different GitHub event types

🛠️ Installation

Quick Setup

# Clone the repository
git clone https://github.com/oheyek/GitHub-User-Activity.git
cd GitHub-User-Activity

# Install dependencies
pip install -r requirements.txt

# Install as a CLI tool (optional)
pip install -e .

Using as Installed CLI

After installation, you can use github-activity directly:

github-activity octocat

Using Python Script

Alternatively, run directly with Python:

python main.py octocat

🎯 Usage

Basic Usage

# Fetch activity for a GitHub user
github-activity <username>

# Examples
github-activity octocat
github-activity torvalds
github-activity gvanrossum

Output

The tool will:

1. Fetch the user's recent public activity from GitHub API
2. Parse and format the activity into readable messages
3. Save the activity to a text file named <username>_activity.txt
4. Display a success message

📋 Supported Activity Types

The CLI tracks and displays the following GitHub activities:

Event Type	Description	Example Output
PushEvent	Code commits pushed	"Pushed 3 commits to user/repo."
IssuesEvent	Issue creation/updates	"Opened an issue in user/repo."
PullRequestEvent	Pull request activities	"Opened a pull request #42 in user/repo."
ForkEvent	Repository forks	"Forked user/repo."
WatchEvent	Repository stars	"Starred user/repo."
CreateEvent	Branch/tag creation	"Created a new branch in user/repo."
DeleteEvent	Branch/tag deletion	"Deleted a branch in user/repo."
IssueCommentEvent	Issue comments	"Created a comment on issue #15 at user/repo."
PullRequestReviewEvent	PR reviews	"Submitted a review on pull request #23 in user/repo."
ReleaseEvent	Release management	"Published a release in user/repo."
GollumEvent	Wiki edits	"Edited the wiki in user/repo."
MemberEvent	Collaborator changes	"Added member username in user/repo."

📊 Output Format

Console Output

$ github-activity octocat
Activity saved to file successfully.

File Output (username_activity.txt)

Pushed 2 commits to octocat/Hello-World.
Starred microsoft/vscode.
Opened an issue in octocat/Spoon-Knife.
Forked rails/rails.

🗂️ File Structure

GitHub-User-Activity/
├── main.py           # Main application logic
├── requirements.txt  # Python dependencies
├── setup.py         # Package setup configuration
└── README.md        # This file

🔧 Technical Details

• Language: Python 3.8+
• API: GitHub REST API v3
• Dependencies: requests library
• Storage: Text file output
• Rate Limiting: Respects GitHub API rate limits

🚦 Error Handling

The CLI provides helpful error messages for common issues:

• User not found: "User {username} has not been found."
• API errors: "API error appeared: code {status_code}"
• Missing username: "Error: Invalid usage. Proper command format: github-activity "
• No activity: "The user has no public activity."

📝 API Response Handling

The tool handles various GitHub API response codes:

• 200: Success - processes and displays activity
• 404: User not found
• Other codes: API error with status code

🤝 Contributing

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

📘 Examples

Typical Workflow

# Check activity for different users
github-activity octocat
github-activity torvalds
github-activity gvanrossum

# Files are automatically created
ls *.txt
# octocat_activity.txt  torvalds_activity.txt  gvanrossum_activity.txt

# View saved activity
cat octocat_activity.txt

Sample Output

$ github-activity octocat
Activity saved to file successfully.

$ cat octocat_activity.txt
Pushed 1 commits to octocat/Hello-World.
Starred rails/rails.
Opened an issue in octocat/Spoon-Knife.
Created a comment on issue #1 at octocat/Hello-World.
Forked microsoft/vscode.

⚡ Performance Notes

• Fetches the most recent 30 public events per user (GitHub API default)
• Minimal processing overhead
• Efficient text file output
• No persistent storage requirements

🔧 Extending Event Support

The CLI currently handles the most common GitHub event types. However, GitHub has additional event types that are less frequently used. If you encounter an event type that isn't supported, you can easily extend the functionality:

1. Identify the missing event: Check the GitHub API documentation for event types
2. Add to the events dictionary: In main.py, add your event type to the events dictionary in the detect_activity() function
3. Format the message: Create a descriptive message following the existing pattern

Example of adding a new event type:

"NewEventType": {
    "message": f"Performed action in {repo_name}."
}

Contributing: If you add support for additional event types, please consider contributing back to the project via a pull request to help other users!

📄 License

This project is open source and available under the MIT License.

---

Happy GitHub Tracking! 🎉

Author

Made with ❤️ by ohey

---

If you find this project useful, consider buying me a coffee!

https://roadmap.sh/projects/github-user-activity