---

````markdown
# GitHub Contribution Heatmap Updater (Mirror & LFS)

This repository contains scripts to:

1. Mirror repositories from Gitea to GitHub.
2. Rewrite commit emails to your GitHub account for heatmap updates.
3. Handle large/LFS-based repositories that fail normal mirroring.
````
---

## Full Workflow

### Step 1: Mirror normal repositories from Gitea to GitHub

Run the main mirroring script to copy all normal repositories from your Gitea account to GitHub.

```bash
python gitea-github-mirror.py
````

**What it does:**

* Fetches all public repositories from Gitea.
* Creates corresponding repositories on GitHub (if they don’t already exist).
* Mirrors all branches and tags to GitHub.

> ⚠️ If some repositories fail during this step (typically large or LFS-based repos), they will be handled in later steps.

---

### Step 2: Update contribution graph for successfully mirrored repositories

After mirroring, update commits and push to GitHub to reflect contributions on your heatmap.

```bash
python mirror-contribution-graph.py
```

**Example:**

```bash
python mirror-contribution-graph.py 
```

**What it does:**

1. Fetches the latest commits from the local mirrored repo.
2. Rewrites all commit author emails to your GitHub email.
3. Pushes all branches and tags to GitHub, updating your contribution heatmap.

> ⚠️ This step is for **normal (non-LFS) repositories**.

---

### Step 3: Push failed/LFS repositories

For repositories that failed in Step 1 (usually large/LFS-based), use the `lfs-push-repo.sh` script.

**Run:**

```bash
sh lfs-push-repo.sh <repo_name> <gitea_url> <github_url>
```

**Example:**

```bash
sh lfs-push-repo.sh solo-level-app-automation https://gitea.domain.com/user/project.git https://github.com/user/project.git
```

**Arguments:**

* `<repo_name>`: Repository name.
* `<gitea_url>`: Original repository URL on Gitea.
* `<github_url>`: GitHub repository URL already created by the mirroring script.

> ✅ This ensures LFS files and history are pushed to the GitHub repository created in Step 1.

---

### Step 4: Update contribution graph for LFS repositories

After pushing the LFS repository, rewrite commits to your GitHub email for the heatmap.

**Run:**

```bash
python mirror-lfs-contribution-graph.py <repo_name> <path_to_local_repo>
```

**Example:**

```bash
python mirror-lfs-contribution-graph.py solo-level-app-automation ./git_repo_project_files/solo-level-app-automation/
```

**What it does:**

1. Fetches the latest commits from the local LFS repo.
2. Rewrites all commit emails to your GitHub email.
3. Pushes all branches and tags to GitHub, updating your contribution heatmap.

---

## Configuration

Set GitHub credentials inside the Python scripts:

```python
GITHUB_USER = "<your GitHub username>"
GITHUB_EMAIL = "<your GitHub email associated with GitHub account>"
GITHUB_TOKEN = "<your GitHub personal access token (PAT)>"
```

* The PAT must have **repo permissions** to push commits.

---

## Logs

* Each run generates a timestamped log file.

  * Example: `mirror_log_20251212_001638.log`
* Logs include:

  * Repositories processed
  * Commit rewriting info
  * Push status
  * Any errors

---

## Notes

* Install `git-lfs`

```bash
sudo apt update
sudo apt install git-lfs
git lfs install
```

* Install `git-filter-repo` for Python scripts:

```bash
pip install git-filter-repo
```

* Commits preserve timestamps but rewrite author emails.
* Pushing with `--mirror` overwrites remote branches/tags — **use carefully**.

---

## Example Directory Layout

```
project-root/
│
├─ gitea-github-mirror.py
├─ mirror-contribution-graph.py
├─ lfs-push-repo.sh
├─ mirror-lfs-contribution-graph.py
├─ gitea_repos/                  # mirrored normal non bare repo's (non working dir)
│   ├─ repo1
│   ├─ repo2
│   └─ ...
└─ git_repo_project_files/       # LFS / working repos
    ├─ lfs-repo1
    ├─ lfs-repo2
    └─ ...
```

---

## Summary of Execution Order

1. **Mirror normal repositories:**

   ```bash
   python gitea-github-mirror.py
   ```

2. **Update contribution graph for mirrored normal repos:**

   ```bash
   python mirror-contribution-graph.py
   ```

3. **Push failed/LFS repositories:**

   ```bash
   sh lfs-push-repo.sh <repo_name> <gitea_url> <github_url>
   ```

4. **Update contribution graph for LFS repositories:**

   ```bash
   python mirror-lfs-contribution-graph.py <repo_name> <path_to_local_repo>
   ```

> Following this order ensures **all normal and LFS-based repositories** are mirrored, commits rewritten, and contribution heatmap updated correctly.