@fuad24/gitbridge 0.1.0 β 0.1.1
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.
- package/README.md +160 -164
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,223 +1,219 @@
|
|
|
1
|
-
|
|
1
|
+
# GitBridge
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/@fuad24/gitbridge)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://www.typescriptlang.org/)
|
|
6
|
+
[](https://github.com/FuadTesfaye/gitbridge/actions)
|
|
4
7
|
|
|
5
|
-
|
|
6
|
-
### *Universal Git Identity, Multi-Account & Provider Management Layer*
|
|
8
|
+
GitBridge is a lightweight CLI and credential management layer that automates Git identities, provider accounts, and SSH keys across projects and directories.
|
|
7
9
|
|
|
8
|
-
|
|
9
|
-
<b>Seamlessly manage identities, provider accounts, and SSH keys across Git workflows without wrapping or replacing native Git.</b>
|
|
10
|
-
</p>
|
|
10
|
+
It operates entirely locally through native Git and SSH configuration hooks (`includeIf`, `credential.helper`, and `~/.ssh/config`), requiring no wrappers or changes to standard `git` commands.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
<a href="https://github.com/FuadTesfaye/gitbridge/actions"><img src="https://img.shields.io/badge/Tests-44%2F44%20Passed-2ea44f?style=for-the-badge&logo=githubactions&logoColor=white" alt="Tests" /></a>
|
|
14
|
-
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-5.8-3178c6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript" /></a>
|
|
15
|
-
<a href="https://bun.sh/"><img src="https://img.shields.io/badge/Bun-1.3-fbf0df?style=for-the-badge&logo=bun&logoColor=black" alt="Bun" /></a>
|
|
16
|
-
<a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-f1c40f?style=for-the-badge" alt="License: MIT" /></a>
|
|
17
|
-
<a href="./extension"><img src="https://img.shields.io/badge/IDE-VS%20Code%20%7C%20Cursor%20%7C%20Antigravity-8a2be2?style=for-the-badge&logo=visualstudiocode&logoColor=white" alt="IDE Extension" /></a>
|
|
18
|
-
</p>
|
|
12
|
+
---
|
|
19
13
|
|
|
20
|
-
|
|
21
|
-
<a href="#-quick-start"><b>β‘ Quick Start</b></a> β’
|
|
22
|
-
<a href="#-why-gitbridge"><b>π‘ Why GitBridge?</b></a> β’
|
|
23
|
-
<a href="#-fast-command-matrix-gitbridge--gb"><b>β¨οΈ Fast Commands</b></a> β’
|
|
24
|
-
<a href="#-ide-extension-vs-code-cursor--antigravity"><b>π₯οΈ IDE Extension</b></a> β’
|
|
25
|
-
<a href="#-security-model--local-only-architecture"><b>π Security</b></a>
|
|
26
|
-
</p>
|
|
14
|
+
## Features
|
|
27
15
|
|
|
28
|
-
|
|
16
|
+
- **Directory-Based Identity Routing**: Automatically switch author names, emails, and GPG/SSH signing keys based on repository paths using Git's native `includeIf` mechanism.
|
|
17
|
+
- **SSH Host & Key Isolation**: Route distinct SSH keys to separate accounts on the same provider (e.g. personal vs. work GitHub) using isolated `Host` aliases with `IdentitiesOnly yes`.
|
|
18
|
+
- **Native OS Credential Storage**: Store personal access tokens in OS-native secure keychains (Linux Secret Service, macOS Keychain, Windows Credential Manager) with an AES-256-GCM encrypted vault fallback.
|
|
19
|
+
- **Zero Runtime Overhead**: Integrates directly into Git and SSH configuration files. Your terminal, IDEs, and Git GUIs continue to invoke native `git` directly.
|
|
20
|
+
- **Pre-Commit Identity Guard**: Optional pre-commit hook that verifies author email matches the expected directory identity before commits are written.
|
|
21
|
+
- **Dual CLI Binaries**: Provides both `gitbridge` and `gb` commands with concise shorthand aliases.
|
|
22
|
+
- **Editor Extension**: Companion extension for VS Code, Cursor, and Antigravity IDE for visual status bar context and identity switching.
|
|
29
23
|
|
|
30
|
-
|
|
31
|
-
Developer / IDE (VS Code, Cursor, Antigravity)
|
|
32
|
-
β
|
|
33
|
-
(Standard git commands)
|
|
34
|
-
βΌ
|
|
35
|
-
Native Git
|
|
36
|
-
β
|
|
37
|
-
βββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββ
|
|
38
|
-
β β β
|
|
39
|
-
[includeIf / .gitconfig] [credential.helper] [~/.ssh/config]
|
|
40
|
-
β β β
|
|
41
|
-
βΌ βΌ βΌ
|
|
42
|
-
βββββββββββββββββ βββββββββββββββββ βββββββββββββββββ
|
|
43
|
-
βIdentity Engineβ βSecure Keyring β βSSH Host Routerβ
|
|
44
|
-
βpersonal vsworkβ βmacOS/Linux/Winβ βgithub.com-workβ
|
|
45
|
-
βββββββββββββββββ βββββββββββββββββ βββββββββββββββββ
|
|
46
|
-
```
|
|
24
|
+
---
|
|
47
25
|
|
|
48
|
-
|
|
26
|
+
## Installation
|
|
49
27
|
|
|
50
|
-
|
|
28
|
+
### Using npm
|
|
29
|
+
```bash
|
|
30
|
+
npm install -g @fuad24/gitbridge
|
|
31
|
+
```
|
|
51
32
|
|
|
52
|
-
|
|
33
|
+
### Using Bun
|
|
34
|
+
```bash
|
|
35
|
+
bun add -g @fuad24/gitbridge
|
|
36
|
+
```
|
|
53
37
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
| **Plaintext Tokens**: Personal access tokens written in plaintext files or cleartext git configs. | **Hardware Keyring Integration**: Tokens are stored 100% locally in **Linux Secret Service**, **macOS Keychain**, or **Windows Credential Manager**. |
|
|
59
|
-
| **Bloated CLI Wrappers**: Tools that alias or intercept `git` add runtime latency and break editor tools. | **Native-First Architecture**: 0ms overhead. VS Code, Cursor, JetBrains, and terminal execute pure native Git. |
|
|
38
|
+
Verify installation:
|
|
39
|
+
```bash
|
|
40
|
+
gb --version
|
|
41
|
+
```
|
|
60
42
|
|
|
61
43
|
---
|
|
62
44
|
|
|
63
|
-
##
|
|
45
|
+
## Quick Start
|
|
64
46
|
|
|
65
|
-
### 1.
|
|
47
|
+
### 1. Run Setup Wizard
|
|
66
48
|
```bash
|
|
67
|
-
|
|
68
|
-
bun add -g @fuad24/gitbridge
|
|
69
|
-
|
|
70
|
-
# Or via npm
|
|
71
|
-
npm install -g @fuad24/gitbridge
|
|
49
|
+
gb setup
|
|
72
50
|
```
|
|
51
|
+
The interactive wizard guides you through:
|
|
52
|
+
- Creating personal and work identities (name, email, signing keys).
|
|
53
|
+
- Mapping directories to identities (e.g. `~/work/**` -> Work identity).
|
|
54
|
+
- Authenticating provider accounts (GitHub, GitLab, Bitbucket).
|
|
55
|
+
- Activating Git (`~/.gitconfig`) and SSH (`~/.ssh/config`) configuration blocks.
|
|
73
56
|
|
|
74
|
-
### 2.
|
|
57
|
+
### 2. Verify Status & Context
|
|
75
58
|
```bash
|
|
76
|
-
|
|
59
|
+
# Check global status
|
|
60
|
+
gb st
|
|
61
|
+
|
|
62
|
+
# Check identity resolution for the current directory
|
|
63
|
+
gb ctx
|
|
77
64
|
```
|
|
78
|
-
The interactive setup will guide you through:
|
|
79
|
-
1. Configuring your **Personal** and **Work** identities.
|
|
80
|
-
2. Connecting your provider accounts (**GitHub Device Flow**, **GitLab**, or **Bitbucket**).
|
|
81
|
-
3. Defining workspace directory routing rules (e.g. `~/Projects/work/**` $\to$ `work`).
|
|
82
|
-
4. Activating Git and SSH integration points.
|
|
83
65
|
|
|
84
|
-
### 3.
|
|
66
|
+
### 3. Run System Diagnostics
|
|
85
67
|
```bash
|
|
86
68
|
gb doc
|
|
87
69
|
```
|
|
88
|
-
|
|
70
|
+
Verifies Git installation, keyring availability, discovered SSH keys, and provider API reachability.
|
|
89
71
|
|
|
90
72
|
---
|
|
91
73
|
|
|
92
|
-
##
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
|
100
|
-
|
|
|
101
|
-
|
|
|
102
|
-
|
|
|
103
|
-
|
|
|
104
|
-
|
|
|
105
|
-
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
|
109
|
-
|
|
110
|
-
|
|
|
111
|
-
|
|
|
112
|
-
|
|
|
113
|
-
|
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
|
117
|
-
|
|
118
|
-
|
|
|
74
|
+
## Command Reference
|
|
75
|
+
|
|
76
|
+
Both `gitbridge` and `gb` are available:
|
|
77
|
+
|
|
78
|
+
### General & Status
|
|
79
|
+
| Shorthand | Full Command | Description |
|
|
80
|
+
|---|---|---|
|
|
81
|
+
| `gb st` | `gitbridge status` | Display configured identities, accounts, and directory rules |
|
|
82
|
+
| `gb ctx` | `gitbridge context` | Show resolved identity and warnings for the current directory |
|
|
83
|
+
| `gb sw [id]` | `gitbridge switch [id]` | Switch repository identity (`-g` for global default) |
|
|
84
|
+
| `gb init` | `gitbridge init` | Initialize repo profile and install pre-commit guard |
|
|
85
|
+
| `gb doc` | `gitbridge doctor` | Run system and connectivity diagnostics |
|
|
86
|
+
| `gb enable` | `gitbridge enable` | Inject GitBridge configuration blocks into Git and SSH configs |
|
|
87
|
+
| `gb disable` | `gitbridge disable` | Safely remove GitBridge configuration blocks |
|
|
88
|
+
|
|
89
|
+
### Identity Management (`gb id`)
|
|
90
|
+
| Shorthand | Full Command | Description |
|
|
91
|
+
|---|---|---|
|
|
92
|
+
| `gb id ls` | `gitbridge identity list` | List all configured identities |
|
|
93
|
+
| `gb id add` | `gitbridge identity add` | Create a new identity (`--name`, `--email`, `--signing-key`) |
|
|
94
|
+
| `gb id use <id>` | `gitbridge identity use <id>` | Set default global identity |
|
|
95
|
+
| `gb id rm <id>` | `gitbridge identity remove <id>` | Remove an identity |
|
|
96
|
+
|
|
97
|
+
### Account & Authentication (`gb acc`, `gb auth`)
|
|
98
|
+
| Shorthand | Full Command | Description |
|
|
99
|
+
|---|---|---|
|
|
100
|
+
| `gb acc ls` | `gitbridge account list` | List authenticated provider accounts |
|
|
101
|
+
| `gb acc rm <id>` | `gitbridge account remove <id>` | Remove account and delete credentials from OS keyring |
|
|
102
|
+
| `gb auth login [provider]` | `gitbridge auth login` | Authenticate with GitHub, GitLab, or Bitbucket |
|
|
103
|
+
| `gb auth logout <provider>` | `gitbridge auth logout` | Log out and revoke stored tokens |
|
|
104
|
+
|
|
105
|
+
### Directory Rules (`gb rules`)
|
|
106
|
+
| Shorthand | Full Command | Description |
|
|
107
|
+
|---|---|---|
|
|
108
|
+
| `gb rules ls` | `gitbridge rule list` | List directory mapping rules |
|
|
109
|
+
| `gb rules add <path> <id>` | `gitbridge rule add` | Map a directory path to an identity |
|
|
110
|
+
| `gb rules rm <id>` | `gitbridge rule remove <id>` | Delete a directory rule |
|
|
111
|
+
|
|
112
|
+
### Remotes & Multi-Push (`gb rem`, `gb push`)
|
|
113
|
+
| Shorthand | Full Command | Description |
|
|
114
|
+
|---|---|---|
|
|
115
|
+
| `gb rem ls` | `gitbridge remote list` | List remotes for current repository |
|
|
116
|
+
| `gb rem add <name> <url>` | `gitbridge remote add` | Add remote with automatic SSH host alias routing |
|
|
117
|
+
| `gb push --all` | `gitbridge push --all` | Push active branch to all configured remotes concurrently |
|
|
119
118
|
|
|
120
119
|
---
|
|
121
120
|
|
|
122
|
-
##
|
|
123
|
-
|
|
124
|
-
GitBridge includes a built-in extension in [`extension/`](./extension) compatible with **VS Code**, **Cursor**, **Windsurf**, and **Google Antigravity IDE**:
|
|
121
|
+
## How It Works
|
|
125
122
|
|
|
126
|
-
|
|
123
|
+
### 1. Git Identity Routing via `includeIf`
|
|
124
|
+
GitBridge generates a modular Git configuration file at `~/.gitbridge/gitconfig` and injects an `include` directive into your `~/.gitconfig`:
|
|
127
125
|
|
|
126
|
+
```gitconfig
|
|
127
|
+
# ~/.gitconfig
|
|
128
|
+
# --- BEGIN GITBRIDGE MANAGED BLOCK ---
|
|
129
|
+
[include]
|
|
130
|
+
path = ~/.gitbridge/gitconfig
|
|
131
|
+
# --- END GITBRIDGE MANAGED BLOCK ---
|
|
128
132
|
```
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
β β β
|
|
139
|
-
β β βΌ IDENTITIES [+] β
|
|
140
|
-
β β β personal (Fuad Tesfaye <personal@example.com>) β
|
|
141
|
-
β β β work (Fuad Tesfaye <work@company.com>) β
|
|
142
|
-
β β β
|
|
143
|
-
β β βΌ ACCOUNTS & PROVIDERS [+] β
|
|
144
|
-
β β π GitHub: @FuadTesfaye (OAuth Keyring) β
|
|
145
|
-
β β π¦ GitLab: @fuad_corp (PAT) β
|
|
146
|
-
β β β
|
|
147
|
-
β β βΌ DIRECTORY RULES [+] β
|
|
148
|
-
β β π ~/Personal β personal β
|
|
149
|
-
β β π ~/Projects/work β work β
|
|
150
|
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
|
151
|
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
|
152
|
-
β Status Bar: [$(person) personal: Fuad Tesfaye] [$(github) @FuadTesfaye] β
|
|
153
|
-
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
|
|
133
|
+
|
|
134
|
+
Directory rules compile into conditional includes:
|
|
135
|
+
```gitconfig
|
|
136
|
+
# ~/.gitbridge/gitconfig
|
|
137
|
+
[includeIf "gitdir:~/work/**"]
|
|
138
|
+
path = ~/.gitbridge/identities/work.gitconfig
|
|
139
|
+
|
|
140
|
+
[includeIf "gitdir:~/personal/**"]
|
|
141
|
+
path = ~/.gitbridge/identities/personal.gitconfig
|
|
154
142
|
```
|
|
155
143
|
|
|
156
|
-
|
|
144
|
+
### 2. SSH Account Isolation
|
|
145
|
+
When multiple accounts use the same Git provider, GitBridge configures host aliases in `~/.ssh/config` to prevent SSH key collisions:
|
|
146
|
+
|
|
147
|
+
```sshconfig
|
|
148
|
+
Host github.com-work
|
|
149
|
+
HostName github.com
|
|
150
|
+
User git
|
|
151
|
+
IdentityFile ~/.ssh/id_work
|
|
152
|
+
IdentitiesOnly yes
|
|
153
|
+
|
|
154
|
+
Host github.com-personal
|
|
155
|
+
HostName github.com
|
|
156
|
+
User git
|
|
157
|
+
IdentityFile ~/.ssh/id_personal
|
|
158
|
+
IdentitiesOnly yes
|
|
159
|
+
```
|
|
157
160
|
|
|
158
|
-
###
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
161
|
+
### 3. Secure Credential Helper
|
|
162
|
+
GitBridge implements the standard Git credential helper protocol:
|
|
163
|
+
```bash
|
|
164
|
+
git config --global credential.helper "gitbridge credential"
|
|
165
|
+
```
|
|
166
|
+
Credentials queried by Git are resolved from:
|
|
167
|
+
1. **Linux**: Secret Service API (`libsecret` / `secret-tool`)
|
|
168
|
+
2. **macOS**: Keychain Services (`/usr/bin/security`)
|
|
169
|
+
3. **Windows**: Windows Credential Manager (DPAPI)
|
|
170
|
+
4. **Headless/Fallback**: Local encrypted vault (`~/.gitbridge/vault.enc`, AES-256-GCM with PBKDF2 key derivation)
|
|
163
171
|
|
|
164
172
|
---
|
|
165
173
|
|
|
166
|
-
##
|
|
174
|
+
## Identity Resolution Order
|
|
167
175
|
|
|
168
|
-
|
|
176
|
+
When determining the active identity for a Git repository, GitBridge applies the following precedence:
|
|
169
177
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
- **Windows**: Windows Credential Manager (DPAPI-encrypted).
|
|
175
|
-
- π **Air-Gapped / Headless Fallback**: In environments without a graphical keychain daemon (e.g. CI containers), credentials are encrypted in `~/.gitbridge/vault.enc` using **AES-256-GCM** with a **PBKDF2** machine-unique derivation key (100,000 rounds of SHA-256 with cryptographically random salt and 12-byte IV).
|
|
176
|
-
- π **Restricted POSIX Permissions**: All configuration and generated files enforce strict permission modes:
|
|
177
|
-
- `~/.gitbridge/` directory: `0700` (`rwx------`, owner only)
|
|
178
|
-
- Config, key & vault files: `0600` (`rw-------`, owner only)
|
|
179
|
-
- ποΈ **SSH Key Isolation**: Dedicated `Host <host>-<account_id>` blocks enforce `IdentitiesOnly yes`, ensuring the SSH agent only presents the specific key mapped to that accountβpreventing cross-account identity leaks.
|
|
178
|
+
1. **Local Repository Profile**: Explicit override configured in `.git/config` or `.gitbridge/repo.json`.
|
|
179
|
+
2. **Directory Rule**: Most specific matching `includeIf "gitdir:..."` rule.
|
|
180
|
+
3. **Global Default**: The fallback identity marked as default in GitBridge.
|
|
181
|
+
4. **System Git Config**: Existing global `user.name` and `user.email` in `~/.gitconfig`.
|
|
180
182
|
|
|
181
183
|
---
|
|
182
184
|
|
|
183
|
-
##
|
|
184
|
-
|
|
185
|
-
When Git or GitBridge resolves an identity for any directory:
|
|
185
|
+
## IDE Extension
|
|
186
186
|
|
|
187
|
-
|
|
187
|
+
GitBridge includes an extension for VS Code, Cursor, and Antigravity IDE (available in [`extension/`](./extension)):
|
|
188
188
|
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
CheckRepo -- Yes --> ApplyRepo["Apply Repository Identity"]
|
|
193
|
-
CheckRepo -- No --> CheckRule{"Matches Directory includeIf Rule?"}
|
|
194
|
-
CheckRule -- Yes --> ApplyRule["Apply Directory Rule Identity"]
|
|
195
|
-
CheckRule -- No --> CheckGlobal{"GitBridge Default Identity?"}
|
|
196
|
-
CheckGlobal -- Yes --> ApplyGlobal["Apply GitBridge Global Default"]
|
|
197
|
-
CheckGlobal -- No --> ApplySystem["Fallback to System Git Config"]
|
|
198
|
-
|
|
199
|
-
ApplyRepo --> Exec["Execute Native Git Command Seamlessly"]
|
|
200
|
-
ApplyRule --> Exec
|
|
201
|
-
ApplyGlobal --> Exec
|
|
202
|
-
ApplySystem --> Exec
|
|
203
|
-
```
|
|
189
|
+
- **Status Bar Indicator**: Real-time display of the resolved identity and account for the active file.
|
|
190
|
+
- **Sidebar Explorer**: Interactive view of active context, configured identities, authenticated accounts, and directory rules.
|
|
191
|
+
- **Live State Synchronization**: File watcher updates the IDE UI immediately when identities or configurations change via CLI.
|
|
204
192
|
|
|
205
193
|
---
|
|
206
194
|
|
|
207
|
-
##
|
|
208
|
-
|
|
209
|
-
GitBridge is verified with a comprehensive automated test suite covering unit schemas, credential stores, injectors, URL parsers, and full Git lifecycle integrations:
|
|
195
|
+
## Development & Testing
|
|
210
196
|
|
|
211
197
|
```bash
|
|
212
|
-
#
|
|
198
|
+
# Clone the repository
|
|
199
|
+
git clone https://github.com/FuadTesfaye/gitbridge.git
|
|
200
|
+
cd gitbridge
|
|
201
|
+
|
|
202
|
+
# Install dependencies
|
|
203
|
+
bun install
|
|
204
|
+
|
|
205
|
+
# Run test suite (44 unit & integration tests)
|
|
213
206
|
bun test
|
|
214
207
|
|
|
215
|
-
#
|
|
208
|
+
# Typecheck
|
|
216
209
|
bun run typecheck
|
|
210
|
+
|
|
211
|
+
# Build CLI and extension bundles
|
|
212
|
+
bun run build
|
|
217
213
|
```
|
|
218
214
|
|
|
219
215
|
---
|
|
220
216
|
|
|
221
|
-
##
|
|
217
|
+
## License
|
|
222
218
|
|
|
223
|
-
MIT Β© [Fuad Tesfaye](https://github.com/FuadTesfaye)
|
|
219
|
+
[MIT](LICENSE) Β© [Fuad Tesfaye](https://github.com/FuadTesfaye)
|