# GitHub Follower Tracker

This project is a simple Flask web application that tracks your GitHub followers, following, unfollowers, and new followers. It allows you to monitor changes in your GitHub social connections, filter out certain users, and see which users are not following you back.

Features

• Followers: View a list of all users currently following you.
• Following: View a list of all users you are currently following.
• Unfollowers: See users who have unfollowed you since the last time you checked.
• Not Following Back: View users you follow but who do not follow you back.
• New Followers: Track users who have followed you within the last 3 days.
• Ignore List: Specify users who should be excluded from the "Not Following Back" list.

## Requirements

- **Python 3.6+**
- **Flask**: A lightweight WSGI web application framework.
- **Requests**: A simple HTTP library for Python.
- **GitHub API Token**: A GitHub personal access token to authenticate API requests.

Setup

1. Clone the Repository

git clone https://github.com/yourusername/GitHub-followers-tracker.git
cd GitHub-followers-tracker.git

2. Set Up a Virtual Environment (Optional but Recommended)

python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\activate

3. Install the Required Dependencies

You can install the required dependencies using the requirements.txt file included in the repository:

pip install -r requirements.txt

4. Configuration

Creating the .env File

• In the project root, you will find a file named .env.example. This file contains placeholders for your GitHub username and API token.
• Rename this file to .env.

mv .env.example .env

• Open the .env file and replace the placeholders with your actual GitHub username and API token.

GITHUB_USERNAME=your_github_username
GITHUB_TOKEN=your_github_personal_access_token

Renaming Example Files

To ensure the application runs correctly, you need to rename the example files to their correct names:

• Rename ignore_list.txt.example to ignore_list.txt:

  mv ignore_list.txt.example ignore_list.txt

• Rename new_followers.json.example to new_followers.json:

  mv new_followers.json.example new_followers.json

• Rename previous_followers.txt.example to previous_followers.txt:

  mv previous_followers.txt.example previous_followers.txt

These files are essential for tracking followers, filtering users, and recording changes.

Why You Need the .env and Other Files

• GitHub Username: This is your GitHub handle. It is required to fetch your followers and following lists.
• GitHub API Token: This token is used to authenticate requests to the GitHub API. While the script can work without it, the GitHub API has rate limits for unauthenticated requests. Using a token allows for a higher rate limit, especially useful if you have many followers.
• ignore_list.txt: This file is used to exclude certain users from the "Not Following Back" section.
• new_followers.json: This file tracks new followers along with the time they started following you.
• previous_followers.txt: This file keeps a record of your previous followers to determine who has unfollowed you.

5. File Structure

Ensure your project directory looks like this:

GitHub-followers-tracker/
│
├── app.py                          # The main Flask application
├── previous_followers.txt          # Stores the list of previous followers
├── new_followers.json              # Stores new followers with timestamps
├── ignore_list.txt                 # Stores usernames to ignore
├── requirements.txt                # Lists all the Python dependencies
├── static/
│   └── styles.css                  # The CSS file for styling the HTML pages
├── templates/
│   └── index.html                  # The HTML template for the main page
└── .env/                          # Virtual environment directory (optional, but recommended)

6. Explanation of Key Files

.env

• Purpose: Stores your GitHub username and personal access token securely.
• Usage: The Flask application reads this file to authenticate API requests and fetch your follower data.

previous_followers.txt

• Purpose: Keeps a record of your followers from the last time you ran the script.
• Usage: This file is automatically generated and updated by the script. It is used to determine who has unfollowed you and who is new.

new_followers.json

• Purpose: Stores a list of new followers along with the timestamp of when they followed you.
• Usage: This file is automatically generated and updated by the script. It is used to track new followers and display them in the "New Followers" section for up to 3 days.

ignore_list.txt

• Purpose: Allows you to specify usernames that should be excluded from the "Not Following Back" list.
• Usage: Manually create this file and list one username per line. The script will read this file and exclude those users from the "Not Following Back" section.

7. Running the Application

Start the Flask development server by running:

FLASK_APP=app.py flask run

Or on Windows:

set FLASK_APP=app.py
flask run

Then open your web browser and go to http://127.0.0.1:5000/ to view the application.

8. Usage

• Followers: Click on the "Followers" section to expand and see your current followers.
• Following: Click on the "Following" section to expand and see who you're following.
• Unfollowers: Click on the "Unfollowers" section to see who has unfollowed you since the last check.
• Not Following Back: Click on the "Not Following Back" section to see users you follow who do not follow you back, excluding those in your ignore_list.txt.
• New Followers: Click on the "New Followers" section to see who has started following you in the last 3 days.

9. Customization

• Ignore List: Add usernames to ignore_list.txt to exclude them from the "Not Following Back" list.
• New Follower Retention: The app.py script is configured to show new followers for 3 days. You can modify the timedelta(days=3) in the script to change this duration.

10. License

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

11. Contributing

If you'd like to contribute, please fork the repository and use a feature branch. Pull requests are warmly welcome.

12. Troubleshooting

If you encounter a JSONDecodeError when running the application, it might be due to an empty or malformed new_followers.json file. The script has been designed to handle such cases by reinitializing the file as necessary.

---

This project is a simple tool for managing and tracking your GitHub followers. It can be extended with additional features, such as notifications or integration with other platforms.

### Summary of Additions:

1. **Renaming Example Files**: Instructions are added for renaming `ignore_list.txt.example`, `new_followers.json.example`, and `previous_followers.txt.example` to their proper file names.
2. **Explanation**: The README now clearly explains why these files are needed and how they interact with the script.

requirements.txt

Here is the requirements.txt file again, which should be placed in your project’s root directory:

Flask==2.1.2
requests==2.28.1
python-decouple==3.8
requests==2.32.3