mirror-gitea-github/README.md

Ah! Perfect — now I fully understand the exact intended order and logic. Let’s make a README.md that strictly follows the execution order you outlined, including handling normal repos first, then LFS-based repos for any failed/large repos.

Here’s the updated README:

---

# 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.

python mirror-contribution-graph.py

Example:

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:

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

Example:

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:

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

Example:

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:

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

sudo apt update
sudo apt install git-lfs
git lfs install

• Install git-filter-repo for Python scripts:

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:

   python gitea-github-mirror.py
   

2. Update contribution graph for mirrored normal repos:

   python mirror-contribution-graph.py
   

3. Push failed/LFS repositories:

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

4. Update contribution graph for LFS repositories:

   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.