git-pulsar 0.9.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
git_pulsar/__init__.py
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: git-pulsar
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Summary: Automated, paranoid git backups for students and casual coding.
|
|
5
|
+
Author-email: jackson.ferguson0@gmail.com
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Requires-Python: >=3.12
|
|
8
|
+
Description-Content-Type: text/markdown
|
|
9
|
+
|
|
10
|
+
# π Git Pulsar (v0.9.0)
|
|
11
|
+
|
|
12
|
+
[](https://github.com/jacksonfergusondev/git-pulsar/actions)
|
|
13
|
+
[](https://www.python.org/downloads/)
|
|
14
|
+
[](LICENSE)
|
|
15
|
+
[](https://github.com/astral-sh/ruff)
|
|
16
|
+
[](https://github.com/pre-commit/pre-commit)
|
|
17
|
+
|
|
18
|
+
**Automated, paranoid git backups for students and casual coding.**
|
|
19
|
+
|
|
20
|
+
Git Pulsar is a background daemon that wakes up every 15 minutes, commits your work to a secluded `wip/pulsar` branch, and pushes it to your remote. It ensures that even if your laptop dies, your uncommitted work is safe on the serverβwithout polluting your main history.
|
|
21
|
+
|
|
22
|
+
---
|
|
23
|
+
|
|
24
|
+
## β‘ Features
|
|
25
|
+
|
|
26
|
+
- **Set & Forget:** Runs silently in the background via `launchd` (macOS) or `systemd` (Linux).
|
|
27
|
+
- **Non-Intrusive:** Commits are pushed to a separate branch (`wip/pulsar`). Your `main` branch stays clean.
|
|
28
|
+
- **Smart Checks:**
|
|
29
|
+
- Detects if the repo is busy (merging/rebasing) and yields.
|
|
30
|
+
- Prevents accidental upload of large files (>100MB).
|
|
31
|
+
- Auto-generates `.gitignore` for Python/LaTeX projects if missing.
|
|
32
|
+
- **System Integration:** Native desktop notifications on success or failure.
|
|
33
|
+
|
|
34
|
+
## π¦ Installation
|
|
35
|
+
|
|
36
|
+
### macOS (Recommended)
|
|
37
|
+
Install via Homebrew to handle the daemon registration automatically.
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
brew tap jacksonfergusondev/tap
|
|
41
|
+
brew install git-pulsar
|
|
42
|
+
brew services start git-pulsar
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
### Linux / Generic
|
|
46
|
+
Install via `uv` (or `pipx`) to isolate the environment, then register the systemd service.
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
uv tool install git-pulsar
|
|
50
|
+
git-pulsar install-service --interval 300 # Optional: Run every 5 mins (default: 900s)
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
## π Usage
|
|
54
|
+
|
|
55
|
+
### 1. Activate a Repository
|
|
56
|
+
Navigate to any project you want to back up and initialize Pulsar.
|
|
57
|
+
|
|
58
|
+
```bash
|
|
59
|
+
cd ~/University/Astro401
|
|
60
|
+
git-pulsar
|
|
61
|
+
```
|
|
62
|
+
*This registers the path in the local registry (`~/.git_pulsar_registry`) and ensures the `wip/pulsar` branch exists.*
|
|
63
|
+
|
|
64
|
+
### 2. Work Normally
|
|
65
|
+
You do not need to do anything else. Pulsar wakes up every 15 minutes to:
|
|
66
|
+
1. Check for changes.
|
|
67
|
+
2. Commit them to `wip/pulsar`.
|
|
68
|
+
3. Push to `origin`.
|
|
69
|
+
|
|
70
|
+
### 3. Manual Backup
|
|
71
|
+
If you want to force a backup immediately (e.g., right before closing your laptop), run:
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
git-pulsar now
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### 4. Monitoring & Control
|
|
78
|
+
Pulsar provides tools to check what's happening behind the scenes.
|
|
79
|
+
|
|
80
|
+
**Check Status:**
|
|
81
|
+
See if the background daemon is running and when the last backup happened.
|
|
82
|
+
```bash
|
|
83
|
+
git-pulsar status
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**View Changes:**
|
|
87
|
+
See exactly what is different between your current work and the last backup (includes untracked files).
|
|
88
|
+
```bash
|
|
89
|
+
git-pulsar diff
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
**Pause Backups:**
|
|
93
|
+
Stop Pulsar from running on a specific repo during heavy refactoring.
|
|
94
|
+
```bash
|
|
95
|
+
git-pulsar pause
|
|
96
|
+
# ... do messy work ...
|
|
97
|
+
git-pulsar resume
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
**View Logs:**
|
|
101
|
+
Tail the background service logs in real-time.
|
|
102
|
+
```bash
|
|
103
|
+
git-pulsar log
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### 5. Restore a File
|
|
107
|
+
If you messed up a file and need to grab the latest version from the backup:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
git-pulsar restore src/main.py
|
|
111
|
+
```
|
|
112
|
+
*This pulls the file from `wip/pulsar` into your working directory. It will warn you if you have uncommitted changes.*
|
|
113
|
+
|
|
114
|
+
### 6. Finalize Your Work
|
|
115
|
+
When you are ready to submit or merge your work back to main:
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
git-pulsar finalize
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
*This automates the squashing process: it switches to `main`, merges your backup history into a single commit, and resets the backup branch so you are ready for the next assignment.*
|
|
122
|
+
|
|
123
|
+
## βοΈ Configuration
|
|
124
|
+
|
|
125
|
+
You can customize global behavior by creating `~/.config/git-pulsar/config.toml`.
|
|
126
|
+
|
|
127
|
+
**Default Configuration:**
|
|
128
|
+
```toml
|
|
129
|
+
[core]
|
|
130
|
+
backup_branch = "wip/pulsar"
|
|
131
|
+
remote_name = "origin"
|
|
132
|
+
|
|
133
|
+
[limits]
|
|
134
|
+
# 5MB log rotation
|
|
135
|
+
max_log_size = 5242880
|
|
136
|
+
# Skip files larger than 100MB
|
|
137
|
+
large_file_threshold = 104857600
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## π Stopping the Service
|
|
141
|
+
|
|
142
|
+
To deregister the background daemon and stop all backups:
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
git-pulsar uninstall-service
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
## π§ Requirements
|
|
149
|
+
|
|
150
|
+
- **Python 3.12+**
|
|
151
|
+
- **Headless Auth:** Your git authentication must be non-interactive (SSH keys or a cached Credential Helper). Pulsar runs in the background and cannot prompt for passwords.
|
|
152
|
+
|
|
153
|
+
## π οΈ Development
|
|
154
|
+
|
|
155
|
+
This project uses modern Python tooling.
|
|
156
|
+
|
|
157
|
+
1. **Clone and Install Dependencies:**
|
|
158
|
+
```bash
|
|
159
|
+
git clone https://github.com/jacksonferguson/git-pulsar.git
|
|
160
|
+
cd git-pulsar
|
|
161
|
+
uv sync
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
2. **Setup Pre-commit Hooks:**
|
|
165
|
+
```bash
|
|
166
|
+
pre-commit install
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
3. **Run Tests:**
|
|
170
|
+
We use `pytest` for testing and `hypothesis` for property-based testing.
|
|
171
|
+
```bash
|
|
172
|
+
uv run pytest
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## π Project Structure
|
|
176
|
+
|
|
177
|
+
```text
|
|
178
|
+
.
|
|
179
|
+
βββ LICENSE
|
|
180
|
+
βββ pyproject.toml
|
|
181
|
+
βββ README.md
|
|
182
|
+
βββ uv.lock
|
|
183
|
+
βββ src
|
|
184
|
+
β βββ __init__.py
|
|
185
|
+
β βββ cli.py # Entry point & repo setup logic
|
|
186
|
+
β βββ daemon.py # Core backup loop & git operations
|
|
187
|
+
β βββ service.py # Background service installer (launchd/systemd)
|
|
188
|
+
βββ tests
|
|
189
|
+
βββ test_cli.py
|
|
190
|
+
βββ test_daemon.py
|
|
191
|
+
βββ test_properties.py
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
## π License
|
|
195
|
+
|
|
196
|
+
This project is licensed under the [MIT License](LICENSE).
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
git_pulsar/__init__.py,sha256=vSDfuy5jQlxWL1_If_ppa_O0zxpi-Y6EgylMDEjIoYw,56
|
|
2
|
+
git_pulsar-0.9.0.dist-info/METADATA,sha256=k5T6Ix9_JL37MPw5oxnaDB6N9Aaa8HplyJ09TE8iKEM,5658
|
|
3
|
+
git_pulsar-0.9.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
|
|
4
|
+
git_pulsar-0.9.0.dist-info/entry_points.txt,sha256=nB41ptd9zi9Xu6zmMXP8-EprPW3A54IiZ1SbviMuTYU,80
|
|
5
|
+
git_pulsar-0.9.0.dist-info/licenses/LICENSE,sha256=29F5Dm0FvGigEbT-pzbDtV9PFLKUvQhIxmvGaRnsS74,1073
|
|
6
|
+
git_pulsar-0.9.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Jackson Ferguson
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|