GitHub Repository .env File Synchronizer

A Python script to synchronize .env files between local GitHub repositories and a central backup directory.

The tool supports bidirectional synchronization, conflict detection, and safe backups without deleting any files.

---

Table of Contents

• Purpose
• Features
• Installation
• Usage
• Argument Structure
• Examples
• How It Works
• Sync Modes
• File Naming Strategy
• Conflict Handling
• File Detection
• Testing
• Project Structure
• Workflow Examples
• Sync Report
• Ignored Directories
• Safety Features
• Platform Support
• Troubleshooting
• Security Note
• License

---

Purpose

Keep all .env configuration files from multiple GitHub repositories synchronized in a single backup location.

This enables:

• Centralized backups
• Easy restoration on new machines
• Safe bidirectional synchronization between repositories and backup

---

Features

• Bidirectional synchronization (two-way)
• One-way synchronization (repo-to-backup, backup-to-repo)
• Content-based change detection using file hashes
• Conflict detection with non-destructive conflict files
• Automatic backup organization by repository
• JSON report generated after each run
• Smart directory filtering
• Comprehensive .env file detection

---

Installation

1. Ensure Python 3.6 or higher is installed
2. Clone or download the sync_env.py script
3. No external dependencies are required (standard library only)

---

Usage

Basic Commands

# Bidirectional synchronization (default)
python sync_env.py /path/to/repositories
python sync_env.py /path/to/repositories /path/to/backup
python sync_env.py /path/to/repositories /path/to/backup two-way

# One-way synchronization: repositories -> backup
python sync_env.py /path/to/repositories /path/to/backup repo-to-backup

# One-way synchronization: backup -> repositories
python sync_env.py /path/to/repositories /path/to/backup backup-to-repo

Argument Structure

Syntax

python sync_env.py <repos_folder> [backup_folder] [mode]

Parameters

• repos_folder (required) Path to the directory containing GitHub repositories.

• backup_folder (optional) Path to the backup directory. Default: ~/.env_backups

• mode (optional) Synchronization mode:

  • two-way (default)

  • repo-to-backup

  • backup-to-repo

Examples

Windows

python sync_env.py C:\Users\username\projects
python sync_env.py C:\Users\username\projects D:\backups\env two-way

Linux / macOS

python sync_env.py /home/username/projects
python sync_env.py /home/username/projects /backup/env-files repo-to-backup

How It Works

Before Synchronization

repositories/
├── frontend-app/
│   ├── .env
│   └── .env.production
├── backend-api/
│   ├── .env
│   └── config/
│       └── database.env
└── mobile-app/
    └── .env

After Synchronization (repo-to-backup)

~/.env_backups/
├── frontend-app/
│   ├── .env
│   ├── env_frontend-app_root.txt
│   └── frontend-app_.env.production
├── backend-api/
│   ├── .env
│   ├── env_backend-api_root.txt
│   └── backend-api_database.env
├── mobile-app/
│   ├── .env
│   └── env_mobile-app_root.txt
└── sync_report.json

Sync Modes

two-way (default)

Synchronizes changes in both directions. If both versions differ, a conflict file is created.

repo-to-backup

Copies .env files from repositories to the backup directory only.

backup-to-repo

Restores .env files from the backup directory into repositories.

File Naming Strategy

Repository File Backup File(s) Created Description

---

.env .env, env_<repo>_root.txt Original + safe descriptive copy .env.local <repo>_.env.local Prefixed to avoid conflicts config.env <repo>_config.env Prefixed to avoid conflicts database.env <repo>_database.env Prefixed to avoid conflicts

Conflict Handling

• When the same file exists in both locations and contents differ:

.env
.env.conflict_20240204T174505

• No file is overwritten

• Both versions are preserved

• Conflicts must be resolved manually

File Detection

The script detects the following patterns:

• .env

• .env.* (e.g. .env.local, .env.production)

• *.env (e.g. config.env, database.env)

• Files containing .env and ending with .env

Testing

Run All Tests

python run_tests.py

Run Specific Modules

python run_tests.py --module test_unit
python run_tests.py --module test_integration

Run Specific Tests

python run_tests.py --test tests.test_unit.TestHashFunctions
python run_tests.py --test tests.test_unit.TestHashFunctions.test_calculate_file_hash_normal

Project Structure

dot-env-handler/
├── sync_env.py
├── run_tests.py
├── README.md
├── tests/
│   ├── __init__.py
│   ├── helpers.py
│   ├── test_unit.py
│   └── test_integration.py
└── .gitignore

Workflow Examples

• Initial Backup

python sync_env.py ~/projects ~/backups/env-files repo-to-backup

• Regular Synchronization

python sync_env.py ~/projects ~/backups/env-files two-way

• Restore on New Machine

python sync_env.py ~/new-projects ~/backups/env-files backup-to-repo

Sync Report

After each run, a JSON report is generated:

{
  "timestamp": "2024-02-04T17:45:05",
  "repos_folder": "/path/to/repositories",
  "backup_folder": "/path/to/backup",
  "mode": "two-way",
  "repos_processed": 3,
  "files_copied_to_backup": 2,
  "files_copied_to_repos": 1,
  "conflicts": [],
  "repositories": []
}

Ignored Directories

The following directories are ignored automatically:

• .git

• node_modules

• __pycache__

• .venv, venv, env

• .idea, .vscode

• dist, build, target

• logs

Safety Features

• No file deletion

• Hash-based change detection

• Conflict files instead of overwriting

• Dual backup copies for root .env files

• Graceful handling of permission errors

Platform Support

• Windows

• Linux

• macOS

Troubleshooting

No .env files found

• Verify repository paths

• Check for nested .env files

• Ensure read permissions

Permission errors

• Verify write access to backup directory

• Run the script with appropriate permissions

Many conflict files

• Review and resolve conflicts manually

• Remove resolved conflict files

• Consider switching to one-way sync when appropriate

Security Note

.env files often contain sensitive data.

Recommendations:

• Store backups in secure locations

• Do not commit backups to version control

• Consider encrypting the backup directory

• Use restrictive file permissions

License

Provided as-is for personal and educational use. Modify and adapt as needed.