🔄 git-sync

A tool to backup and sync your git repositories

Bug report · Feature request

git-sync is a CLI tool designed to help you back up your GitHub repositories. This tool ensures you have a local copy of your repositories, safeguarding against potential issues such as account bans or data loss on GitHub.

By using git-sync, you can easily clone or update your repositories to a specified local directory.

Why git-sync?

Remember when @defunkt GitHub account got banned? Well, he is the co-founder of GitHub so he did get this account un-banned but what if you are not that lucky? Recently I have seen many developers getting their GitHub account banned and losing access to their repositories. Some may be able to recover their account (but there is delay in that) and some may not be able to recover their account at all.

With the increasing reliance on cloud-based repository hosting services like GitHub, it's crucial to have a backup plan. While GitHub is highly reliable, unexpected events like account bans, outages, or accidental deletions can occur.

git-sync provides a straightforward way to back up all your repositories locally, ensuring you have access to your code whenever you need it. It does this by doing a bare clone of all your repositories in a specified directory so that you can recover your code in case of any unforeseen circumstances as well as the file size of your backups is minimal.

Features

• Backup All Repositories: Automatically clone or update all your GitHub repositories to a local directory.
• Bare Clone: Efficiently back up repositories using bare clones to save space and speed up the process.
• Concurrency: Sync multiple repositories concurrently to reduce the time required for backup.
• Configuration File: Easily manage your settings through a YAML configuration file.

Installation

Prerequisites

• Go (version 1.22 or later)
• Git

Using go get

go get github.com/AkashRajpurohit/git-sync

Build from source

git clone https://github.com/AkashRajpurohit/git-sync.git
cd git-sync
go install
go build

With Docker

docker run --rm -v /path/to/config/:/git-sync -v /path/to/backups:/backups ghcr.io/akashrajpurohit/git-sync:latest

Or you can use the docker-compose.yml file to run the container.

services:
  git-sync:
    image: ghcr.io/akashrajpurohit/git-sync:latest
    volumes:
      - /path/to/config/:/git-sync
      - /path/to/backups:/backups

docker-compose up

Download Pre-built Binaries

Pre-built binaries are available for various platforms. You can download the latest release from the Releases page.

Usage

Configuration

Before using git-sync, you need to create a configuration file named config.yml. The default path for the configuration file is ~/.config/git-sync/config.yml.

Here's an example configuration file:

# Configuration file for git-sync
# Default path: ~/.config/git-sync/config.yml
username: your-github-username
token: your-personal-access-token
include_repos: []
exclude_repos: []
backup_dir: /path/to/backup
include_forks: false

Note: The include_repos and exclude_repos fields accept repository name as well as glob patterns. The patterns supported are those defined by filepath.Match.

Here are some dry run examples for different configurations:

Include all repositories that I own (even forks)

username: your-github-username
token: your-personal-access-token
include_repos: []
exclude_repos: []
backup_dir: /path/to/backup
include_forks: true

Include all repositories that I own excluding forks

username: your-github-username
token: your-personal-access-token
include_repos: []
exclude_repos: []
backup_dir: /path/to/backup
include_forks: false

Include all repositories that I own excluding forks and some repositories

username: your-github-username
token: your-personal-access-token
include_repos: []
exclude_repos: ["repo1", "repo2"]
backup_dir: /path/to/backup
include_forks: false

Include only specific repositories

username: your-github-username
token: your-personal-access-token
include_repos: ["repo1"]
exclude_repos: []
backup_dir: /path/to/backup
include_forks: false

NOTE: In the above example if you passed exclude_repos as well then it will be ignored since you have passed include_repos. So an example like below will still have same effect as above and only "repo1" will be backed up.

username: your-github-username
token: your-personal-access-token
include_repos: ["repo1"]
exclude_repos: ["repo2", "repo3"]
backup_dir: /path/to/backup
include_forks: false

Include / Exclude repositories using glob patterns

To include all repos which start with repo, you can use the following configuration:

username: your-github-username
token: your-personal-access-token
include_repos: ["repo*"]
exclude_repos: []
backup_dir: /path/to/backup
include_forks: false

Same way you can exclude all repos which start with repo:

username: your-github-username
token: your-personal-access-token
include_repos: []
exclude_repos: ["repo*"]
backup_dir: /path/to/backup
include_forks: false

Commands

Sync Repositories

To sync your repositories, run the following command:

git-sync

This command will clone or update all your repositories to the specified backup directory.

Version

To check the version of git-sync, run the following command:

git-sync version

Help

To view the help message, run the following command:

git-sync help

Setup Periodic Backups

Unix-based Systems

You can set up periodic backups using cron jobs or systemD timers. For example, to back up your repositories every day at 12:00 AM, you can add the following cron job:

0 0 * * * /path/to/git-sync

Replace /path/to/git-sync with the path to the git-sync binary.

Windows

You can set up periodic backups using Task Scheduler. Here's how you can do it:

1. Open Task Scheduler.
2. Click on Create Basic Task.
3. Enter a name and description for the task.
4. Choose the trigger (e.g., Daily).
5. Set the time for the trigger.
6. Choose Start a program as the action.
7. Browse to the git-sync binary.
8. Click Finish to create the task.
9. Right-click on the task and select Run to test it.
10. Your repositories will now be backed up periodically.

Or you can use Powershell script to run the git-sync binary.

$action = New-ScheduledTaskAction -Execute "path\to\git-sync.exe"
$trigger = New-ScheduledTaskTrigger -Daily -At "12:00AM"
Register-ScheduledTask -Action $action -Trigger $trigger -TaskName "GitSyncTask" -Description "Daily Git Sync"

Replace path\to\git-sync.exe with the path to the git-sync binary.

FAQs

How do I create a GitHub personal access token?

You can create a new personal access token by following the steps mentioned here: Creating a personal access token. If you don't want to rotating the tokens after expiry, select the (Classic) option while creating the token and set expiration to Never.

How do I restore from the backups?

The backups generated by git-sync are essentially bare clones of your repositories. To restore a repository, you can simply clone it from the backup directory. For example:

git clone /path/to/backup/repo.git

I want to exclude forks in general but still want to include some specific forks. How can I do that?

You can achieve this by adding the specific forks to the include_repos list in the configuration file and keeping the include_forks flag as false. This way, only the specified forks will be included in the backup.

Example configuration:

username: your-github-username
token: your-personal-access-token
include_repos: ["fork1", "fork2"]
exclude_repos: []
backup_dir: /path/to/backup
include_forks: false

Bugs or Requests 🐛

If you encounter any problems feel free to open an issue. If you feel the project is missing a feature, please raise a ticket on GitHub and I'll look into it. Pull requests are also welcome.

Where to find me? 👀