You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When the notification hits, you have 2 minutes to push.
5
-
Miss it, and your local commits become unreal.
3
+
GitReal is a Git subcommand that turns "I should push later" into a deadline.
6
4
7
-
## What It Is
5
+
When a challenge fires, you have 2 minutes to push your local commits. If you miss the window, GitReal can reset your branch back to its upstream state. By default, it stays in dry-run mode, so you can try the workflow before allowing destructive behavior.
8
6
9
-
GitReal is a Git subcommand distributed as a `git-real` executable. When that binary is on your `PATH`, Git automatically exposes it as:
7
+
The distributed binary is named `git-real`, and Git exposes it to users as:
10
8
11
9
```bash
12
10
git real
13
11
```
14
12
15
-
That means the user-facing command is `git real`, while the shipped executable name is `git-real`.
13
+
## Why You Would Use It
16
14
17
-
## MVP Commands
15
+
- You want a push habit, not just a reminder.
16
+
- You want the pressure of a timer without giving up recovery options.
17
+
- You want to try it safely before enabling real resets.
18
+
19
+
## Quick Start
20
+
21
+
Install:
22
+
23
+
```bash
24
+
go install github.com/watany-dev/gitreal/cmd/git-real@latest
25
+
```
26
+
27
+
Try it in a repository:
18
28
19
29
```bash
20
30
git real init
21
31
git real status
22
32
git real once
33
+
```
34
+
35
+
`git real once`, `git real start`, `git real arm`, and `git real disarm` require `git real init` first. `git real status` and `git real rescue ...` are still available before initialization.
36
+
37
+
If you want GitReal to run continuously in the foreground:
38
+
39
+
```bash
23
40
git real start
41
+
```
42
+
43
+
## What Happens In Practice
44
+
45
+
1. Run `git real init` once per repository.
46
+
2. GitReal stores repo-local config and starts in dry-run mode.
47
+
3. A challenge checks whether your current branch is ahead of its upstream.
48
+
4. If you push in time, nothing happens.
49
+
5. If you miss the deadline:
50
+
51
+
- in dry-run mode, GitReal only tells you what it would have reset
52
+
- in armed mode, GitReal backs up `HEAD` and resets the branch to `@{u}`
53
+
54
+
## Safety First
55
+
56
+
GitReal is intentionally conservative:
57
+
58
+
- Default mode is dry-run.
59
+
- Destructive behavior requires an explicit `git real arm`.
60
+
- Before any reset, GitReal stores the current `HEAD` under `refs/gitreal/backups/...`.
61
+
-`git real rescue restore <ref>` also backs up the current `HEAD` before restoring a backup.
62
+
- Dirty worktree changes are stashed and then restored when possible.
63
+
64
+
If you want real enforcement for the current repository:
65
+
66
+
```bash
24
67
git real arm
68
+
```
69
+
70
+
To go back to safe mode:
71
+
72
+
```bash
25
73
git real disarm
26
-
git real rescue list
27
-
git real rescue restore <ref>
28
74
```
29
75
30
-
## Quick Start
76
+
## Recovery
77
+
78
+
List available backups:
31
79
32
80
```bash
33
-
# install with go install
34
-
go install github.com/watany-dev/gitreal/cmd/git-real@latest
81
+
git real rescue list
82
+
```
35
83
36
-
# initialize the current repository
37
-
git real init
84
+
Restore one:
38
85
39
-
# inspect current state
40
-
git real status
86
+
```bash
87
+
git real rescue restore <ref>
88
+
```
41
89
42
-
# run one dry-run challenge now
43
-
git real once
90
+
## Commands
44
91
45
-
# run the foreground scheduler
46
-
git real start
92
+
```bash
93
+
git real init
94
+
git real status
95
+
git real once [--grace-seconds=120]
96
+
git real start [--grace-seconds=120]
97
+
git real arm
98
+
git real disarm
99
+
git real rescue list
100
+
git real rescue restore <ref>
47
101
```
48
102
49
-
`git real once`, `git real start`, `git real arm`, and `git real disarm` require `git real init` first. `git real status` and `git real rescue ...` remain available before initialization.
103
+
Command intent:
50
104
51
-
## Safety Model
105
+
-`git real init`: enable GitReal for the current repository and write default config
106
+
-`git real status`: show current repo state, upstream, and ahead count
107
+
-`git real once`: run one challenge immediately
108
+
-`git real start`: stay in the foreground and schedule hourly random challenges over time
109
+
-`git real arm`: allow real resets for missed deadlines
110
+
-`git real disarm`: return to dry-run mode
111
+
-`git real rescue ...`: inspect and restore backup refs
52
112
53
-
- Default mode is dry-run.
54
-
- Destructive behavior must be explicitly armed with `git real arm`.
55
-
- Before any reset, GitReal stores the current `HEAD` under `refs/gitreal/backups/...`.
56
-
-`git real rescue restore <ref>` also backs up the current `HEAD` before restoring the selected backup ref.
57
-
- Recovery is done with `git real rescue list` and `git real rescue restore <ref>`.
113
+
## Current Limits
114
+
115
+
This beta currently expects:
58
116
59
-
## Current Implementation
117
+
- the current branch has an upstream branch
118
+
- the repository is not in detached `HEAD`
119
+
- desktop notifications may fail and fall back to terminal output
120
+
-`git real start` is the current scheduler entrypoint
-`internal/challenge`: grace-period constants and normalization
127
+
```bash
128
+
git config --local gitreal.enabled true
129
+
git config --local gitreal.armed false
130
+
git config --local gitreal.graceSeconds 120
131
+
```
77
132
78
-
## Current Constraints
133
+
Current keys:
79
134
80
-
- An upstream branch is required for challenge execution.
81
-
- Detached `HEAD` is not supported.
82
-
- Desktop notifications are best-effort and fall back to terminal output when unavailable.
83
-
-`git real daemon` is not implemented in the current beta.
135
+
-`gitreal.enabled`
136
+
-`gitreal.armed`
137
+
-`gitreal.graceSeconds`
84
138
85
-
## Local Build Target
139
+
## Build From Source
86
140
87
141
```bash
88
142
go build -o git-real ./cmd/git-real
89
143
```
90
144
91
145
## Development
92
146
93
-
Bootstrap and validate locally:
147
+
Project checks:
94
148
95
149
```bash
96
150
go mod download
@@ -99,28 +153,14 @@ make test
99
153
make check
100
154
```
101
155
102
-
Checks included in `make check`:
156
+
`make check` runs formatting, linting, type-check compilation, dead-code detection, and the coverage gate.
103
157
104
-
- formatting check with `gofmt`
105
-
- linting with `go vet` and `staticcheck`
106
-
- type-check/compile with `go test -run '^$' ./...`
107
-
- dead code detection with `deadcode`
108
-
- coverage gate at `95%`
109
-
110
-
Property-based tests are included with the standard library `testing/quick`.
111
-
112
-
## Expected Install Paths
158
+
## Releases
113
159
114
160
Current beta distribution targets:
115
161
116
-
- GitHub Releases with per-OS archives for macOS, Linux, and Windows
117
162
-`go install`
118
-
119
-
Example commands:
120
-
121
-
```bash
122
-
go install github.com/watany-dev/gitreal/cmd/git-real@latest
123
-
```
163
+
- GitHub Releases for macOS, Linux, and Windows
124
164
125
165
Release archives are published as:
126
166
@@ -131,6 +171,6 @@ Release archives are published as:
131
171
-`git-real_windows_amd64.zip`
132
172
-`SHA256SUMS`
133
173
134
-
## Notes
174
+
## More Detail
135
175
136
-
Detailed design notes, command rationale, Git plumbing choices, and the original prototype notes are stored in [docs/development-memo.md](/workspaces/gitreal/docs/development-memo.md).
176
+
Design notesand implementation rationale live in [docs/development-memo.md](/workspaces/gitreal/docs/development-memo.md).
0 commit comments