projectclone 4.0.1
Create exact, self-contained, reproducible project snapshots including git, caches, configs, and environment artifacts.
License: MIT
Requires Python: >=3.8
Keywords: backup, snapshot, clone, filesystem, archive, project-clone, self-contained-env, developer-tools

<div align="center">
  <img src="https://raw.githubusercontent.com/dhruv13x/projectclone/main/projectclone_logo.png" alt="projectclone logo" width="200"/>
</div>

<div align="center">

<!-- Package Info -->
[![PyPI version](https://img.shields.io/pypi/v/projectclone.svg)](https://pypi.org/project/projectclone/)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/)
![Wheel](https://img.shields.io/pypi/wheel/projectclone.svg)
[![Release](https://img.shields.io/badge/release-PyPI-blue)](https://pypi.org/project/projectclone/)

<!-- Build & Quality -->
[![Build status](https://github.com/dhruv13x/projectclone/actions/workflows/publish.yml/badge.svg)](https://github.com/dhruv13x/projectclone/actions/workflows/publish.yml)
[![Codecov](https://codecov.io/gh/dhruv13x/projectclone/graph/badge.svg)](https://codecov.io/gh/dhruv13x/projectclone)
[![Test Coverage](https://img.shields.io/badge/coverage-90%25%2B-brightgreen.svg)](https://github.com/dhruv13x/projectclone/actions/workflows/test.yml)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/badge/linting-ruff-yellow.svg)](https://github.com/astral-sh/ruff)
![Security](https://img.shields.io/badge/security-CodeQL-blue.svg)

<!-- Usage -->
![Downloads](https://img.shields.io/pypi/dm/projectclone.svg)
![OS](https://img.shields.io/badge/os-Linux%20%7C%20macOS%20%7C%20Windows-blue.svg)
[![Python Versions](https://img.shields.io/pypi/pyversions/projectclone.svg)](https://pypi.org/project/projectclone/)

<!-- License -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- Docs -->
[![Docs](https://img.shields.io/badge/docs-latest-brightgreen.svg)](https://your-docs-link)

</div>


# projectclone 🧬  
### Exact, reproducible, full-state project snapshots — including git, caches, env artifacts & symlinks

---

## 🚀 Overview

`projectclone` creates **exact, faithful, self-contained snapshots** of your project directory, including:

✔ Source code  
✔ `.git` repo & history  
✔ Virtualenvs & caches *(unless excluded)*  
✔ File timestamps, metadata, symlinks  
✔ Configs, logs, local DBs  
✔ Environment-specific state

This enables **true reproducibility** and **safe rollback points** across environments and devices.

### Why this tool?

For developers who need **guaranteed restorable project states**, across:

- Major refactors
- Release checkpoints
- Deployment backups
- Research environments
- Offline disaster recovery
- CI/CD artifact capture
- Termux/mobile development
- Reproducible experiments

> Think:  
> `git commit` + `tar` + `rsync --link-dest` + atomic backup discipline  
> — in one tool.

---

## 🔗 Restore tool

For restoring projectclone backups, use its companion tool:

### 👉 [`projectrestore`](https://github.com/dhruv13x/projectrestore)

| Tool | Responsibility |
|---|---|
`projectclone` | **Create** state snapshots *(non-destructive)*
`projectrestore` | **Apply** snapshots safely *(atomic & secure)*

This design keeps the backup tool safe, focused, and non-destructive — while giving the restore tool full security hardening and atomic restore semantics.

---

## ✨ Features

| Feature | Description |
|---|---|
Full directory clone | Exact deep copy with metadata  
Archive mode | `.tar.gz` with optional SHA-256 manifest  
Incremental mode | Hard-link dedup snapshots (like Time Machine / Borg)  
Atomic safety | Temp staging → atomic move → rollback on fail  
Cross-filesystem safe | Intelligent move vs copy fallback  
Dry-run mode | Preview without modifying anything  
Rotation | Keep only the last N snapshots  
Exclude filters | Glob / substring file exclusion  
Progress UI | Live counters and size reporting  
Termux ready | Works on Android + proot Ubuntu

---

## 📦 Installation

### 🐍 Standard install

```sh
pip install projectclone

📱 Termux / Android

pkg install rsync proot-distro
pip install projectclone


---

🔧 Usage Examples

Basic backup

projectclone backup_1k_tests

Creates:

/sdcard/project_backups/2025-02-03_172501-myproject-backup_1k_tests/


---

Archive mode

projectclone release_v1 --archive

Produces:

release_v1.tar.gz
release_v1.tar.gz.sha256


---

Incremental backup (deduplicated snapshots)

projectclone checkpoint --incremental


---

Exclude files

projectclone nightly --exclude __pycache__ --exclude .mypy_cache


---

Retain last 5 backups

projectclone stable --keep 5


---

Dry-run safety preview

projectclone test --dry-run


---

Full help

projectclone --help


---

🛠 Options Summary

Flag	Meaning

--archive	Create .tar.gz archive
--incremental	Hard-linked incremental mode
--manifest	Size manifest
--manifest-sha	Per-file SHA-256 manifest
--exclude	Exclude patterns
--dest DIR	Custom destination
--dry-run	Preview, no writes
--symlinks	Preserve symlinks
--keep N	Keep only last N backups
--yes	Auto-confirm operations
--verbose	Debug logging



---

🔐 Safety Guarantees

Atomic staging → atomic final move

Secure cleanup on failure

Cross-device move fallback

Drops setuid/setgid bits

Tight log permissions (chmod 600 where supported)

Non-destructive: never overwrites directories



---

📁 Default Paths

Platform	Location

Linux	~/project_backups
Termux	/sdcard/project_backups



---

🧪 Development

pip install -e .[dev]
pytest -v


---

📜 License

MIT — open source & production-friendly.


---

🤝 Contributing

Ideas & PRs welcome — especially around:

Compression tuning (zstd / lz4)

Remote sync (SSH / S3 / GDrive)

Fuse mounts / stream extraction

Config file support



---

⭐ Support

If this tool protects your work, please ⭐️ the repo — your support drives development.

git clone https://github.com/dhruv13x/projectclone


---

🧠 Author

Dhruv13x
Mobile-first DevOps explorer | Rust & Python | Cloud | Termux power-user


---

🧩 Roadmap

.projectcloneignore

zstd / lz4 compression

Remote targets (SSH / S3 / GDrive)

Encrypted archives

GUI wrapper (Android & Desktop)


> Restore is intentionally delegated to
projectrestore → secure, atomic, rollback-safe recovery




---

💬 Final Word

> Code evolves — backups must keep up.
Restore safely — with tools designed for it.



With projectclone, every project state becomes portable, reproducible, and future-proof.

Clone. Freeze. Protect. Restore via projectrestore.


---