⚘ use your pds as a git remote if you want to ⚘
update README: document OAuth + password auth, reflect git-remote-pds rename
+61
-17
+61
-17
README.md
+61
-17
README.md
···
1
-
# pds-git-remote
1
+
# git-remote-pds
2
2
3
3
This is not the most efficient way to do git,
4
4
and is not meant as a replacement for [tangled](https://tangled.org/),
5
-
or for anything really.
5
+
or for anything really.
6
6
7
7
However it seems to work, and it can be used by anyone with a PDS or a bluesky account,
8
8
without installing anything additionally on their server.
9
9
10
10
Tangled currently requires the use of a [knot server](https://tangled.org/tangled.org/core/blob/8dd9e59b99e83e757bcadf11a4bda31fc78e6732/docs/knot-hosting.md)
11
11
as well as the use of ssh keys for git access
12
-
(although from talking with the developers, there is some discussion of
13
-
changing things in the future to allow authentication without ssh keys). pds-git-remote skips these requirements as well as efficiency.
12
+
(although from talking with the developers, there is some discussion of
13
+
changing things in the future to allow authentication without ssh keys). git-remote-pds skips these requirements as well as efficiency.
14
14
15
-
pds-git-remote is a git remote helper that stores repositories on an [AT Protocol](https://atproto.com) Personal Data Server (PDS) directly.
15
+
git-remote-pds is a git remote helper that stores repositories on an [AT Protocol](https://atproto.com) Personal Data Server (PDS) directly.
16
16
```bash
17
-
# log in to your PDS
18
-
git-remote-pds auth login --pds-url https://your-pds.example.com --handle alice.example.com
17
+
# log in to your PDS via OAuth (opens browser)
18
+
git-remote-pds auth oauth-login --handle alice.example.com
19
19
20
20
# push an existing repo
21
21
cd my-project
···
32
32
33
33
- I have done basic tests to confirm that it works,
34
34
- the design and code could be reviewed
35
-
- haven't done any benchmarking
35
+
- haven't done any benchmarking
36
36
37
-
This was actually created as a subtask for a mostly unrelated project (more soon).
37
+
This was actually created as a subtask for a mostly unrelated project (more soon).
38
38
39
39
## git-ssb <3
40
40
41
41
primary inspiration was git-ssb. another tool that may
42
-
not have been the most efficient way to do git,
42
+
not have been the most efficient way to do git,
43
43
but I really loved for multiple reasons ([link](https://scuttlebot.io/apis/community/git-ssb.html))
44
44
45
45
···
52
52
# add the binary to your PATH
53
53
export PATH="$(pwd)/target/debug:${PATH}"
54
54
55
-
# log in to your PDS
56
-
git-remote-pds auth login --pds-url https://your-pds.example.com --handle alice.example.com
55
+
# log in to your PDS (opens browser for authorization)
56
+
git-remote-pds auth oauth-login --handle alice.example.com
57
57
58
58
# push an existing repo
59
59
cd my-project
···
83
83
84
84
## Authentication
85
85
86
-
### `auth login`
86
+
git-remote-pds supports two ways to authenticate with a PDS. Credentials are stored per-handle in `~/.config/pds-git-remote/auth.json`. If you have multiple accounts, each handle has its own credential — git-remote-pds uses the matching handle from the `pds://handle/repo` URL.
87
+
88
+
### OAuth login (recommended)
89
+
90
+
```bash
91
+
git-remote-pds auth oauth-login --handle alice.example.com
92
+
```
93
+
94
+
Opens your browser to authorize with your PDS via AT Protocol OAuth. This uses the loopback client flow (no server required) and stores DPoP-bound tokens locally. Tokens are short-lived (~5 minutes) but include a refresh token for renewal.
95
+
96
+
For a PDS that isn't discoverable via handle resolution (e.g. local dev), pass `--pds-url`:
97
+
98
+
```bash
99
+
git-remote-pds auth oauth-login --handle alice.example.com --pds-url https://your-pds.example.com
100
+
```
101
+
102
+
The `--port` flag controls which localhost port the OAuth callback listens on (default: 8271).
103
+
104
+
### Password login
87
105
88
106
```bash
89
107
git-remote-pds auth login --pds-url https://your-pds.example.com --handle alice.example.com
90
108
```
91
109
92
-
Prompts for your password and stores credentials in `~/.config/pds-git-remote/auth.json`.
110
+
Authenticates with handle + password via `com.atproto.server.createSession` and stores a Bearer token. This is simpler but requires your password (or an app password), and AT Protocol is moving toward deprecating password-based auth in favor of OAuth.
93
111
94
112
### `auth status`
95
113
···
97
115
git-remote-pds auth status
98
116
```
99
117
100
-
Shows stored credentials.
118
+
Shows stored credentials, auth method, and token status:
119
+
120
+
```
121
+
alice.example.com
122
+
did: did:plc:abc123
123
+
pds: https://pds.example.com
124
+
auth: OAuth (DPoP)
125
+
token: valid (expires in 3m 20s)
126
+
127
+
bob.example.com
128
+
did: did:plc:def456
129
+
pds: https://other-pds.example.com
130
+
auth: createSession (Bearer)
131
+
```
101
132
102
133
### `auth logout`
103
134
···
111
142
112
143
| Variable | Description |
113
144
|----------|-------------|
114
-
| `PDS_HANDLE` + `PDS_PASSWORD` | Log in on the fly |
115
-
| `PDS_ACCESS_TOKEN` + `PDS_DID` | Use a token directly |
145
+
| `PDS_HANDLE` + `PDS_PASSWORD` | Log in on the fly via createSession |
146
+
| `PDS_ACCESS_TOKEN` + `PDS_DID` | Use a token directly (Bearer) |
147
+
| `PDS_ACCESS_TOKEN` + `PDS_DID` + `PDS_DPOP_KEY` | Use a DPoP-bound token directly |
116
148
| `PDS_URL` | Override PDS endpoint (skips identity resolution) |
149
+
150
+
Environment variables take priority over stored credentials.
117
151
118
152
## Identity resolution
119
153
···
135
169
# e2e tests (used via scripts with docker, see below)
136
170
cargo test --features e2e
137
171
```
172
+
173
+
### Playwright tests (OAuth flow)
174
+
175
+
End-to-end tests for the OAuth login and push flow using Playwright:
176
+
177
+
```bash
178
+
./playwright-test/run.sh
179
+
```
180
+
181
+
Tests `oauth-login` with browser automation, then pushes and clones to verify.
138
182
139
183
### Local PDS (Docker)
140
184