Skip to content

Commit 4f15fae

Browse files
southpawriter02southpawriter02
committed
feat: Add comprehensive installation guide, bump version to 0.9.0-beta.1, and update repository URLs and dependencies.
1 parent 6034549 commit 4f15fae

File tree

11 files changed

+298
-41
lines changed

11 files changed

+298
-41
lines changed

‎CHANGELOG.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,16 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
77

88
## [Unreleased]
99

10+
## [0.9.0-beta.1] - 2026-01-02
11+
12+
First public beta release establishing distribution foundation.
13+
1014
### Added
15+
- Comprehensive INSTALL.md with instructions for all installation methods
1116
- Docker Hub publishing workflow for multi-architecture images (amd64, arm64)
1217
- Version roadmap documentation for path to v1.0
18+
- README badges for PyPI, Docker Hub, and license
19+
- Docker HEALTHCHECK for container health monitoring
1320

1421
### Changed
1522
- Version scheme updated to 0.9.x beta series before v1.0 release
16-
17-
## [0.9.0] - TBD
18-
19-
First public beta release.
23+
- Updated all placeholder URLs to southpawriter02/git-chronoscope
24+
- Synchronized dependencies across pyproject.toml, setup.py, and requirements.txt
25+
- Homebrew formulas updated for v0.9.0-beta.1
26+
- Improved README installation section with quick install options
2027

2128
### Features
2229
- **Core Functionality**

‎Dockerfile‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ FROM python:3.11-slim
22

33
LABEL maintainer="git-chronoscope"
44
LABEL description="Generate time-lapse videos of Git repository history"
5+
LABEL org.opencontainers.image.source="https://github.com/southpawriter02/git-chronoscope"
6+
LABEL org.opencontainers.image.version="0.9.0-beta.1"
57

68
# Install system dependencies
79
RUN apt-get update && apt-get install -y --no-install-recommends \
@@ -25,5 +27,9 @@ RUN pip install --no-cache-dir -r requirements.txt
2527
# Make entrypoint executable
2628
RUN chmod +x /app/entrypoint.sh
2729

30+
# Healthcheck - verify git-chronoscope can run
31+
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
32+
CMD python -c "from src.main import main; print('OK')" || exit 1
33+
2834
# Set the entrypoint
2935
ENTRYPOINT ["/app/entrypoint.sh"]

‎Formula/git-chronoscope.rb‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,16 @@
11
# git-chronoscope Homebrew Formula
22
# Install: brew install --build-from-source ./Formula/git-chronoscope.rb
3-
# Or via tap: brew tap user/git-chronoscope && brew install git-chronoscope
3+
# Or via tap: brew tap southpawriter02/git-chronoscope && brew install git-chronoscope
44

55
class GitChronoscope < Formula
66
include Language::Python::Virtualenv
77

88
desc "Generate time-lapse visualizations of Git repository evolution"
9-
homepage "https://github.com/user/git-chronoscope"
10-
url "https://github.com/user/git-chronoscope/archive/refs/tags/v1.0.0.tar.gz"
9+
homepage "https://github.com/southpawriter02/git-chronoscope"
10+
url "https://github.com/southpawriter02/git-chronoscope/archive/refs/tags/v0.9.0-beta.1.tar.gz"
1111
sha256 "PLACEHOLDER_SHA256_WILL_BE_UPDATED_ON_RELEASE"
1212
license "MIT"
13-
head "https://github.com/user/git-chronoscope.git", branch: "main"
13+
head "https://github.com/southpawriter02/git-chronoscope.git", branch: "main"
1414

1515
depends_on "python@3.11"
1616
depends_on "ffmpeg"

‎INSTALL.md‎

Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# Installation Guide
2+
3+
git-chronoscope can be installed through multiple methods. Choose the one that best fits your workflow.
4+
5+
## Prerequisites
6+
7+
All installation methods require:
8+
- **FFmpeg** - Required for video encoding ([download](https://ffmpeg.org/download.html))
9+
- **Git** - Required for repository access
10+
11+
## Quick Install
12+
13+
### PyPI (Recommended)
14+
15+
```bash
16+
pip install git-chronoscope
17+
```
18+
19+
### Homebrew (macOS/Linux)
20+
21+
```bash
22+
brew tap southpawriter02/git-chronoscope
23+
brew install git-chronoscope
24+
```
25+
26+
### Docker
27+
28+
```bash
29+
docker pull southpawriter02/git-chronoscope
30+
```
31+
32+
---
33+
34+
## Detailed Installation Instructions
35+
36+
### Option 1: PyPI Package
37+
38+
The simplest way to install git-chronoscope is via pip:
39+
40+
```bash
41+
# Install from PyPI
42+
pip install git-chronoscope
43+
44+
# Or with a specific version
45+
pip install git-chronoscope==0.9.0-beta.1
46+
47+
# Verify installation
48+
git-chronoscope --help
49+
```
50+
51+
**Requirements:**
52+
- Python 3.7 or higher
53+
- FFmpeg installed and in PATH
54+
55+
### Option 2: Homebrew (macOS/Linux)
56+
57+
Install using the Homebrew package manager:
58+
59+
```bash
60+
# Add the tap (first time only)
61+
brew tap southpawriter02/git-chronoscope
62+
63+
# Install
64+
brew install git-chronoscope
65+
66+
# Update to latest version
67+
brew update && brew upgrade git-chronoscope
68+
```
69+
70+
Homebrew will automatically install Python and FFmpeg dependencies.
71+
72+
### Option 3: Standalone Executables
73+
74+
Pre-built executables are available for Windows, macOS, and Linux. No Python installation required.
75+
76+
1. Go to the [Releases page](https://github.com/southpawriter02/git-chronoscope/releases)
77+
2. Download the appropriate file for your platform:
78+
- `git-chronoscope-windows.exe` - Windows
79+
- `git-chronoscope-macos` - macOS
80+
- `git-chronoscope-linux` - Linux
81+
3. Make executable (macOS/Linux):
82+
```bash
83+
chmod +x git-chronoscope-macos # or git-chronoscope-linux
84+
```
85+
4. Run:
86+
```bash
87+
./git-chronoscope-macos /path/to/repo output.mp4
88+
```
89+
90+
**Note:** You still need FFmpeg installed separately.
91+
92+
### Option 4: Docker
93+
94+
Run git-chronoscope in a container with all dependencies pre-installed:
95+
96+
```bash
97+
# Pull the image
98+
docker pull southpawriter02/git-chronoscope
99+
100+
# Run with a local repository
101+
docker run -v /path/to/repo:/repo -v /path/to/output:/output \
102+
southpawriter02/git-chronoscope /repo /output/timelapse.mp4
103+
104+
# With additional options
105+
docker run -v /path/to/repo:/repo -v /path/to/output:/output \
106+
southpawriter02/git-chronoscope /repo /output/timelapse.mp4 \
107+
--format gif --resolution 720p --fps 5
108+
```
109+
110+
### Option 5: From Source
111+
112+
For development or to get the latest changes:
113+
114+
```bash
115+
# Clone the repository
116+
git clone https://github.com/southpawriter02/git-chronoscope.git
117+
cd git-chronoscope
118+
119+
# Create virtual environment (recommended)
120+
python -m venv .venv
121+
source .venv/bin/activate # On Windows: .venv\Scripts\activate
122+
123+
# Install dependencies
124+
pip install -r requirements.txt
125+
126+
# Run directly
127+
python -m src.main /path/to/repo output.mp4
128+
129+
# Or install in development mode
130+
pip install -e .
131+
git-chronoscope /path/to/repo output.mp4
132+
```
133+
134+
### Option 6: GitHub Actions
135+
136+
Use git-chronoscope directly in your CI/CD pipeline:
137+
138+
```yaml
139+
- uses: southpawriter02/git-chronoscope@v1
140+
with:
141+
format: mp4
142+
output-path: timelapse.mp4
143+
resolution: 1080p
144+
```
145+
146+
See [.github/workflows/timelapse.yml](.github/workflows/timelapse.yml) for a complete example.
147+
148+
---
149+
150+
## Verifying Installation
151+
152+
After installation, verify everything works:
153+
154+
```bash
155+
# Check version
156+
git-chronoscope --version
157+
158+
# Show help
159+
git-chronoscope --help
160+
161+
# Test with a repository
162+
git-chronoscope /path/to/any/git/repo test-output.mp4 --dry-run
163+
```
164+
165+
---
166+
167+
## Troubleshooting
168+
169+
### FFmpeg not found
170+
171+
If you see "FFmpeg not found" errors:
172+
173+
**macOS:**
174+
```bash
175+
brew install ffmpeg
176+
```
177+
178+
**Ubuntu/Debian:**
179+
```bash
180+
sudo apt update && sudo apt install ffmpeg
181+
```
182+
183+
**Windows:**
184+
1. Download from https://ffmpeg.org/download.html
185+
2. Extract and add the `bin` folder to your PATH
186+
187+
### Permission denied (macOS standalone)
188+
189+
```bash
190+
chmod +x git-chronoscope-macos
191+
xattr -d com.apple.quarantine git-chronoscope-macos # Remove quarantine flag
192+
```
193+
194+
### Python version issues
195+
196+
git-chronoscope requires Python 3.7+. Check your version:
197+
198+
```bash
199+
python --version
200+
# or
201+
python3 --version
202+
```
203+
204+
---
205+
206+
## Uninstalling
207+
208+
### PyPI
209+
```bash
210+
pip uninstall git-chronoscope
211+
```
212+
213+
### Homebrew
214+
```bash
215+
brew uninstall git-chronoscope
216+
brew untap southpawriter02/git-chronoscope
217+
```
218+
219+
### Docker
220+
```bash
221+
docker rmi southpawriter02/git-chronoscope
222+
```
223+
224+
---
225+
226+
## Next Steps
227+
228+
- Read the [README](README.md) for usage examples
229+
- Check [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for common issues
230+
- See [CONTRIBUTING.md](CONTRIBUTING.md) to contribute

‎README.md‎

Lines changed: 27 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# git-chronoscope
22

3+
[![PyPI version](https://badge.fury.io/py/git-chronoscope.svg)](https://badge.fury.io/py/git-chronoscope)
4+
[![Docker Pulls](https://img.shields.io/docker/pulls/southpawriter02/git-chronoscope)](https://hub.docker.com/r/southpawriter02/git-chronoscope)
5+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6+
37
A command-line tool and web-based GUI that generates a video or animated GIF showing the evolution of a Git repository's codebase. It visualizes file creation, deletion, and code changes, creating a compelling, shareable artifact that tells the story of a project.
48

59
## Features
@@ -13,26 +17,33 @@ A command-line tool and web-based GUI that generates a video or animated GIF sho
1317

1418
## Installation
1519

16-
### Prerequisites
20+
### Quick Install
21+
22+
```bash
23+
# PyPI (recommended)
24+
pip install git-chronoscope
25+
26+
# Homebrew (macOS/Linux)
27+
brew tap southpawriter02/git-chronoscope && brew install git-chronoscope
1728

18-
- Python 3.7+
19-
- Git
20-
- FFmpeg
29+
# Docker
30+
docker pull southpawriter02/git-chronoscope
31+
```
32+
33+
### Prerequisites
2134

22-
Before you begin, ensure you have [FFmpeg](https://ffmpeg.org/download.html) installed and accessible in your system's PATH. FFmpeg is required for video encoding. See [DEPENDENCIES.md](DEPENDENCIES.md) for detailed installation guides.
35+
- **FFmpeg** - Required for video encoding ([download](https://ffmpeg.org/download.html))
36+
- **Git** - Required for repository access
2337

24-
### Steps
38+
See [INSTALL.md](INSTALL.md) for detailed installation instructions including standalone executables and installation from source.
2539

26-
1. **Clone the repository:**
27-
```bash
28-
git clone https://github.com/your-username/git-chronoscope.git
29-
cd git-chronoscope
30-
```
40+
### From Source
3141

32-
2. **Install Python dependencies:**
33-
```bash
34-
pip install -r requirements.txt
35-
```
42+
```bash
43+
git clone https://github.com/southpawriter02/git-chronoscope.git
44+
cd git-chronoscope
45+
pip install -r requirements.txt
46+
```
3647

3748
## Usage
3849

@@ -185,7 +196,7 @@ python -m src.main /path/to/repo output.mp4 --author-colors
185196
Add to your workflow:
186197

187198
```yaml
188-
- uses: your-username/git-chronoscope@v1
199+
- uses: southpawriter02/git-chronoscope@v1
189200
with:
190201
format: html
191202
output-path: timelapse.html

‎homebrew-tap/Formula/git-chronoscope.rb‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@ class GitChronoscope < Formula
55
include Language::Python::Virtualenv
66

77
desc "Generate time-lapse visualizations of Git repository evolution"
8-
homepage "https://github.com/user/git-chronoscope"
9-
url "https://github.com/user/git-chronoscope/archive/refs/tags/v1.0.0.tar.gz"
8+
homepage "https://github.com/southpawriter02/git-chronoscope"
9+
url "https://github.com/southpawriter02/git-chronoscope/archive/refs/tags/v0.9.0-beta.1.tar.gz"
1010
sha256 "PLACEHOLDER_SHA256_WILL_BE_UPDATED_ON_RELEASE"
1111
license "MIT"
12-
head "https://github.com/user/git-chronoscope.git", branch: "main"
12+
head "https://github.com/southpawriter02/git-chronoscope.git", branch: "main"
1313

1414
depends_on "python@3.11"
1515
depends_on "ffmpeg"

‎homebrew-tap/README.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ This repository contains the Homebrew formula for git-chronoscope.
66

77
```bash
88
# Add the tap
9-
brew tap user/git-chronoscope
9+
brew tap southpawriter02/git-chronoscope
1010

1111
# Install
1212
brew install git-chronoscope
@@ -31,7 +31,7 @@ brew upgrade git-chronoscope
3131

3232
```bash
3333
brew uninstall git-chronoscope
34-
brew untap user/git-chronoscope
34+
brew untap southpawriter02/git-chronoscope
3535
```
3636

3737
## From Source

0 commit comments

Comments
 (0)