# coldstore
[](https://pypi.org/project/coldstore/)
[](https://pypi.org/project/coldstore/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/janfasnacht/coldstore/actions)
**Project archival with rich metadata and integrity verification**
coldstore creates compressed project archives with structured metadata (Git repository state, environment details, event notes, timestamps) and comprehensive integrity verification (archive-level, per-file, and manifest checksums).
## Quick Start
### Installation
```bash
pipx install coldstore
```
Or with pip:
```bash
pip install coldstore
```
### Basic Usage
```bash
# Create archive
coldstore freeze ~/project ./archives/ --milestone "Nature submission"
# Verify integrity
coldstore verify ./archives/project-20251018-143022.tar.gz
# Inspect without extracting
coldstore inspect ./archives/project-20251018-143022.tar.gz
```
### Example: Paper Submission
```bash
coldstore freeze ~/research/paper ./archives/ \
--milestone "Nature Neuroscience submission" \
--note "Final version after reviewer comments" \
--contact "PI: jane.doe@university.edu" \
--exclude "*.pyc" \
--exclude "__pycache__"
```
Output:
```
✓ Archive created: ./archives/paper-20251018-143022.tar.gz
- Size: 127.3 MB (compressed from 456.2 MB)
- Files: 1,234
- SHA256: a3d2f1e8...
✓ Git metadata captured:
- Branch: main (commit: abc123...)
- Remote: https://github.com/user/paper
✓ Event metadata:
- Milestone: Nature Neuroscience submission
- Timestamp: 2025-10-18T14:30:22Z
```
## Features
### Event-Driven Metadata
- Milestone/event name and timestamp
- Multiple notes and contact information
- Git repository state (branch, commit, remotes, dirty status)
- Environment details (hostname, user, platform, Python version)
- Per-file SHA256 checksums
### Multi-Level Verification
- Archive-level: SHA256 of entire `.tar.gz`
- File-level: SHA256 for each archived file
- Manifest-level: Validates metadata structure
### Inspection Without Extraction
Explore archive metadata, file listings, and statistics without extracting files.
### Dry-Run Mode
Preview what will be archived before creating files.
## CLI Reference
### `coldstore freeze`
```bash
coldstore freeze [OPTIONS] SOURCE DESTINATION
Options:
--milestone TEXT Event name (e.g., "PNAS submission")
--note TEXT Description note (repeatable)
--contact TEXT Contact information (repeatable)
--name TEXT Custom archive name
--compression-level INT Gzip level 1-9 [default: 6]
--exclude TEXT Exclude pattern (repeatable)
--dry-run Preview without creating files
--no-manifest Skip MANIFEST.json generation
--no-filelist Skip FILELIST.csv.gz generation
--no-sha256 Skip per-file checksums
```
### `coldstore verify`
```bash
coldstore verify ARCHIVE_PATH
```
Performs three-level verification:
- Archive checksum (SHA256 of `.tar.gz`)
- Per-file checksums (from manifest)
- Manifest structure validation
### `coldstore inspect`
```bash
coldstore inspect ARCHIVE_PATH
```
Displays:
- Event metadata (milestone, notes, contacts, timestamp)
- Git state (branch, commit, remote, dirty status)
- Environment (hostname, user, platform)
- Archive statistics (file count, sizes)
- File listing with checksums
## Common Patterns
```bash
# Academic paper with exclusions
coldstore freeze ~/paper ./archives/ \
--milestone "Journal submission" \
--note "Supplementary materials included" \
--contact "Corresponding: prof@university.edu" \
--exclude "*.pyc" --exclude ".venv"
# Grant deliverable
coldstore freeze ~/grant-project ./deliverables/ \
--milestone "NSF Year 2 Deliverable - Award #1234567" \
--contact "PI: pi@university.edu" \
--contact "Program Officer: po@nsf.gov"
# Dry-run preview
coldstore freeze ~/project ./archives/ --milestone "Test" --dry-run
# Maximum compression for long-term storage
coldstore freeze ~/project ./archives/ \
--compression-level 9 \
--milestone "Archive"
```
## Archive Structure
```
project-20251018-143022/
├── project-20251018-143022.tar.gz # Compressed archive
├── MANIFEST.json # Structured metadata
├── FILELIST.csv.gz # File listing + checksums
└── SHA256SUMS # Archive checksum
```
### MANIFEST.json
```json
{
"event": {
"milestone": "Nature submission",
"timestamp": "2025-10-18T14:30:22Z",
"notes": ["Final version"],
"contacts": ["PI: jane.doe@university.edu"]
},
"git": {
"branch": "main",
"commit": "abc123...",
"remote": "https://github.com/user/repo",
"is_dirty": false
},
"environment": {
"hostname": "workstation",
"username": "user",
"platform": "Linux-5.15.0-x86_64",
"python_version": "3.11.4"
},
"archive": {
"path": "project-20251018-143022.tar.gz",
"size_bytes": 133456789,
"sha256": "a3d2f1e8..."
},
"files": {
"total_count": 1234,
"total_size_bytes": 456789012,
"checksums": {
"src/main.py": "d4e5f6...",
"src/utils.py": "e7f8a9..."
}
}
}
```
## Documentation
- **[docs/USAGE.md](docs/USAGE.md)**: Detailed command reference and troubleshooting
- **[CHANGELOG.md](CHANGELOG.md)**: Version history
## Requirements
- Python 3.9+
- Git (optional, for repository metadata)
## Development
### Setup
```bash
git clone https://github.com/janfasnacht/coldstore.git
cd coldstore
poetry install
poetry run pytest # 295 tests
```
### Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md)
### Testing
```bash
make test # Run all tests
make test-cov # With coverage
make lint # Code quality checks
```
## License
MIT License - see [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": "https://github.com/janfasnacht/coldstore",
"name": "coldstore",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "archival, metadata, research, academic, snapshot, verification, git, compliance, audit",
"author": "Jan Fasnacht",
"author_email": "jan.fasnacht@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/00/96/3b933754fdbf17f57c2829e285975b0709b469accf71fed92883f5a0d58e/coldstore-1.0.0.tar.gz",
"platform": null,
"description": "# coldstore\n\n[](https://pypi.org/project/coldstore/)\n[](https://pypi.org/project/coldstore/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/janfasnacht/coldstore/actions)\n\n**Project archival with rich metadata and integrity verification**\n\ncoldstore creates compressed project archives with structured metadata (Git repository state, environment details, event notes, timestamps) and comprehensive integrity verification (archive-level, per-file, and manifest checksums).\n\n## Quick Start\n\n### Installation\n\n```bash\npipx install coldstore\n```\n\nOr with pip:\n```bash\npip install coldstore\n```\n\n### Basic Usage\n\n```bash\n# Create archive\ncoldstore freeze ~/project ./archives/ --milestone \"Nature submission\"\n\n# Verify integrity\ncoldstore verify ./archives/project-20251018-143022.tar.gz\n\n# Inspect without extracting\ncoldstore inspect ./archives/project-20251018-143022.tar.gz\n```\n\n### Example: Paper Submission\n\n```bash\ncoldstore freeze ~/research/paper ./archives/ \\\n --milestone \"Nature Neuroscience submission\" \\\n --note \"Final version after reviewer comments\" \\\n --contact \"PI: jane.doe@university.edu\" \\\n --exclude \"*.pyc\" \\\n --exclude \"__pycache__\"\n```\n\nOutput:\n```\n\u2713 Archive created: ./archives/paper-20251018-143022.tar.gz\n - Size: 127.3 MB (compressed from 456.2 MB)\n - Files: 1,234\n - SHA256: a3d2f1e8...\n\n\u2713 Git metadata captured:\n - Branch: main (commit: abc123...)\n - Remote: https://github.com/user/paper\n\n\u2713 Event metadata:\n - Milestone: Nature Neuroscience submission\n - Timestamp: 2025-10-18T14:30:22Z\n```\n\n## Features\n\n### Event-Driven Metadata\n- Milestone/event name and timestamp\n- Multiple notes and contact information\n- Git repository state (branch, commit, remotes, dirty status)\n- Environment details (hostname, user, platform, Python version)\n- Per-file SHA256 checksums\n\n### Multi-Level Verification\n- Archive-level: SHA256 of entire `.tar.gz`\n- File-level: SHA256 for each archived file\n- Manifest-level: Validates metadata structure\n\n### Inspection Without Extraction\nExplore archive metadata, file listings, and statistics without extracting files.\n\n### Dry-Run Mode\nPreview what will be archived before creating files.\n\n## CLI Reference\n\n### `coldstore freeze`\n\n```bash\ncoldstore freeze [OPTIONS] SOURCE DESTINATION\n\nOptions:\n --milestone TEXT Event name (e.g., \"PNAS submission\")\n --note TEXT Description note (repeatable)\n --contact TEXT Contact information (repeatable)\n --name TEXT Custom archive name\n --compression-level INT Gzip level 1-9 [default: 6]\n --exclude TEXT Exclude pattern (repeatable)\n --dry-run Preview without creating files\n --no-manifest Skip MANIFEST.json generation\n --no-filelist Skip FILELIST.csv.gz generation\n --no-sha256 Skip per-file checksums\n```\n\n### `coldstore verify`\n\n```bash\ncoldstore verify ARCHIVE_PATH\n```\n\nPerforms three-level verification:\n- Archive checksum (SHA256 of `.tar.gz`)\n- Per-file checksums (from manifest)\n- Manifest structure validation\n\n### `coldstore inspect`\n\n```bash\ncoldstore inspect ARCHIVE_PATH\n```\n\nDisplays:\n- Event metadata (milestone, notes, contacts, timestamp)\n- Git state (branch, commit, remote, dirty status)\n- Environment (hostname, user, platform)\n- Archive statistics (file count, sizes)\n- File listing with checksums\n\n## Common Patterns\n\n```bash\n# Academic paper with exclusions\ncoldstore freeze ~/paper ./archives/ \\\n --milestone \"Journal submission\" \\\n --note \"Supplementary materials included\" \\\n --contact \"Corresponding: prof@university.edu\" \\\n --exclude \"*.pyc\" --exclude \".venv\"\n\n# Grant deliverable\ncoldstore freeze ~/grant-project ./deliverables/ \\\n --milestone \"NSF Year 2 Deliverable - Award #1234567\" \\\n --contact \"PI: pi@university.edu\" \\\n --contact \"Program Officer: po@nsf.gov\"\n\n# Dry-run preview\ncoldstore freeze ~/project ./archives/ --milestone \"Test\" --dry-run\n\n# Maximum compression for long-term storage\ncoldstore freeze ~/project ./archives/ \\\n --compression-level 9 \\\n --milestone \"Archive\"\n```\n\n## Archive Structure\n\n```\nproject-20251018-143022/\n\u251c\u2500\u2500 project-20251018-143022.tar.gz # Compressed archive\n\u251c\u2500\u2500 MANIFEST.json # Structured metadata\n\u251c\u2500\u2500 FILELIST.csv.gz # File listing + checksums\n\u2514\u2500\u2500 SHA256SUMS # Archive checksum\n```\n\n### MANIFEST.json\n\n```json\n{\n \"event\": {\n \"milestone\": \"Nature submission\",\n \"timestamp\": \"2025-10-18T14:30:22Z\",\n \"notes\": [\"Final version\"],\n \"contacts\": [\"PI: jane.doe@university.edu\"]\n },\n \"git\": {\n \"branch\": \"main\",\n \"commit\": \"abc123...\",\n \"remote\": \"https://github.com/user/repo\",\n \"is_dirty\": false\n },\n \"environment\": {\n \"hostname\": \"workstation\",\n \"username\": \"user\",\n \"platform\": \"Linux-5.15.0-x86_64\",\n \"python_version\": \"3.11.4\"\n },\n \"archive\": {\n \"path\": \"project-20251018-143022.tar.gz\",\n \"size_bytes\": 133456789,\n \"sha256\": \"a3d2f1e8...\"\n },\n \"files\": {\n \"total_count\": 1234,\n \"total_size_bytes\": 456789012,\n \"checksums\": {\n \"src/main.py\": \"d4e5f6...\",\n \"src/utils.py\": \"e7f8a9...\"\n }\n }\n}\n```\n\n## Documentation\n\n- **[docs/USAGE.md](docs/USAGE.md)**: Detailed command reference and troubleshooting\n- **[CHANGELOG.md](CHANGELOG.md)**: Version history\n\n## Requirements\n\n- Python 3.9+\n- Git (optional, for repository metadata)\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/janfasnacht/coldstore.git\ncd coldstore\npoetry install\npoetry run pytest # 295 tests\n```\n\n### Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n### Testing\n\n```bash\nmake test # Run all tests\nmake test-cov # With coverage\nmake lint # Code quality checks\n```\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Project archival with structured metadata (Git state, environment, notes) and multi-level integrity verification",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/janfasnacht/coldstore#readme",
"Homepage": "https://github.com/janfasnacht/coldstore",
"Repository": "https://github.com/janfasnacht/coldstore"
},
"split_keywords": [
"archival",
" metadata",
" research",
" academic",
" snapshot",
" verification",
" git",
" compliance",
" audit"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4d3c5c23b01d2ce9ea963188abb7f34d41254bce723be9c7647b1dc7964240f4",
"md5": "214e428a358f918896be0196af0baff6",
"sha256": "e6d4d9200ff805541e8762202aee19457d0c76712652ff65a8e37efa65042241"
},
"downloads": -1,
"filename": "coldstore-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "214e428a358f918896be0196af0baff6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 49972,
"upload_time": "2025-10-19T05:16:52",
"upload_time_iso_8601": "2025-10-19T05:16:52.122675Z",
"url": "https://files.pythonhosted.org/packages/4d/3c/5c23b01d2ce9ea963188abb7f34d41254bce723be9c7647b1dc7964240f4/coldstore-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "00963b933754fdbf17f57c2829e285975b0709b469accf71fed92883f5a0d58e",
"md5": "312f9cf5e5392301fae7e3b2cab36b54",
"sha256": "8794697c3d0e53ee014542ca76c0848facb5362e6729a4f6296932e9b05aebb0"
},
"downloads": -1,
"filename": "coldstore-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "312f9cf5e5392301fae7e3b2cab36b54",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 44924,
"upload_time": "2025-10-19T05:16:53",
"upload_time_iso_8601": "2025-10-19T05:16:53.501976Z",
"url": "https://files.pythonhosted.org/packages/00/96/3b933754fdbf17f57c2829e285975b0709b469accf71fed92883f5a0d58e/coldstore-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 05:16:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "janfasnacht",
"github_project": "coldstore",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "coldstore"
}
JSON
