⚠️ Known issues

• The reset saved.json script does not reset all data correctly.
• After the forest grows beyond 7 trees (175 commits), the background does not clear automatically; the forest then stops growing and no variation appears for higher-contribution users.

At the moment, this limits the project for users with more than 175 contributions. Fixing the reset and background logic is on the roadmap. Despite these limitations, GitForest demonstrates GitHub Actions integration, JSON saving/loading, and SVG-based visualization of contribution data.

🤨 What is it?

GitForest is a dynamic, visually driven GitHub profile enhancement that turns your contribution history into a forest and it lives in github actions. The more you code, the bigger the forest grows. The forest will be periodically reset to prevent the forest from becoming to large however the data (how many forests you've filled) will be stored and displayed. GitForest helps you visualize consistency, progress and growth in a more organic, motivating and fun way.

🌱 What does it look like?

Depending on what you set in config (BACKGROUND_COLOR variable) you will get one of these.

🌳 How Does the Forest Grow?

• 🌲 One spruce = 25 commits
• 🌸 One cherry blossom tree = 10 pull requests
• 🌲🌲🌲 One forest = 7 trees
• 🪴 More coming soon...

✨ Features

• 🌳 Visual growth: When you contribute more you see trees grow and new elements appear as the ecosystem grows
• 📈 Progress tracker: See how many forests you've filled over time
• 🛠️ GitHub integration: Works directly with your contribution data

⚡ Quick Start

1. Fork this repo
2. Add API_KEY secret with your personal access token
3. Set USERNAME, YEAR, and BACKGROUND_COLOR
4. Run the reset saved.json workflow

🚀 Installation

1. Create a fork

2. Go to your profile settings
3. Scroll down and click developer settings

4. Click on personal access tokens and then on token (classic)

5. Click generate new token (for general use)
6. Name it however you like and select repo scope

7. Scroll down and click generate token (make sure to copy it)
8. Go back to the forked repository and go to repository settings
9. Click on secrets and variables then actions

10. In repository secrets add the API_KEY secret and paste your personal access token
11. Click on variables and
    • add and edit USERNAME to match your username
    • add and edit YEAR to match current year
    • add and edit BACKGROUND_COLOR (scroll down to Config)
    • also add the variable DISPLAY_FORESTS and set it as yes/true if you would like to have the forests grown in your profile README otherwise set it as no/false
12. Go to repository actions and click on reset saved.json (ci might not show yet)

13. Click run workflow

14. Done! The CI script runs automatically every 10 minutes which is responsible for updating the svg
15. If you want to have it in your profile README go to assets/forest.svg and copy the raw link to it then paste it in your README like this (if you also want to display the forests you have grown add this line </!-- forests -->0</!-- endforests --> (without the slashes) and set DISPLAY_FORESTS variable to true or yes)

🔧 Config

Currently only the background color can be customized. Please note that the background color will actually update when the forest fills up or if the script runs for the first time. Here are what they look like and what to type in BACKGROUND_COLOR variable:

• mystic or purple:

• golden or yellow:

• frost or blue:

• emerald or green:

🧩 Technologies

• C++
  • rapidjson library
  • pugixml library
  • catch2 framework
• GitHub API
• SVGs (made in figma)

🤝 Contributing

Have ideas for GitForest? Feel free to open an issue or submit a pull request!

📅 Roadmap

• PRIORITY:
• Complete at least 2 Trees or other elements
• Create Background
• Make README
• Test if a library for embedding SVG is working
• Test different inputs
• Integrate GitHub API
• Fix script
• Fix background not clearing
• MIGHT TAKE LONGER:
• Change backgrounds depending on day streaks
• Add more forest elements
• Choosing a background color palette