carapace-sh/carapace-bin / skills/git
git
FlaggedUse when working with Git — object model, references, index, branching, merging, rebasing, remotes, diffs, config, hooks, worktrees, submodules, and plumbing commands. Triggers on: "git", "git branch", "git commit", "git merge", "git rebase", "git checkout", "git stash", "git reset", "git submodule", "git worktree", "git blame", "git bisect", "git reflog", "git hooks", "git config".
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.6 KB |
| references/branching-merging.md | markdown | 8.8 KB |
| references/cli.md | markdown | 12.3 KB |
| references/concepts.md | markdown | 8.7 KB |
| references/config.md | markdown | 11.4 KB |
| references/diff-patch.md | markdown | 9.5 KB |
| references/hooks.md | markdown | 12.2 KB |
| references/index.md | markdown | 7.7 KB |
| references/internals.md | markdown | 14.4 KB |
| references/objects.md | markdown | 10.1 KB |
| references/rebase.md | markdown | 10.3 KB |
| references/refs.md | markdown | 10.3 KB |
| references/remotes.md | markdown | 11.1 KB |
| references/workflows.md | markdown | 12.4 KB |
| references/worktree.md | markdown | 11.2 KB |
references/remotes.md
View on GitHub# Git Remotes and Transfer Protocols
How Git communicates with remote repositories — remotes, refspecs, fetch, push, pull, and the wire protocols.
> **Source of truth**: <https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols>, <https://git-scm.com/docs/gitprotocol-pack>. For **reference types and refspecs**, see [refs.md](refs.md). For **object storage and packfiles**, see [objects.md](objects.md).
## Remote Configuration
### Adding and Managing Remotes
```bash
git remote add origin https://github.com/user/repo.git
git remote add upstream https://github.com/original/repo.git
git remote -v # List with URLs
git remote set-url origin <new-url> # Change URL
git remote rename <old> <new> # Rename
git remote remove <name> # Remove
git remote show origin # Show remote details
```
### Remote Config
Each remote is stored in `.git/config`:
```ini
[remote "origin"]
url = https://github.com/user/repo.git
fetch = +refs/heads/*:refs/remotes/origin/*
pushurl = git@github.com:user/repo.git # Different push URL
push = refs/heads/main:refs/heads/main # Push refspec
tagOpt = --no-tags # Don't auto-fetch tags
```
### Multiple Push URLs
```bash
git remote set-url --add --push origin <url1>
git remote set-url --add --push origin <url2>
```
Pushes to both URLs simultaneously.
## Refspecs
A refspec maps source refs to destination refs during fetch and push:
```
[+]<src>:<dst>
```
- `+` prefix = force update (allow non-fast-forward)
- `<src>` = source ref (remote for fetch, local for push)
- `<dst>` = destination ref
### Default Fetch Refspec
```
+refs/heads/*:refs/remotes/origin/*
```
Fetches all remote branches and stores them as remote-tracking branches under `refs/remotes/origin/`.
### Default Push Refspec
If not explicitly configured, `git push` uses the matching branch name:
```
refs/heads/<branch>:refs/heads/<branch>
```
With `push.default = current`, it pushes the current branch to a same-named branch on the remote.
### Push Default Modes
| Mode | Behavior |
|------|----------|
| `nothing` | Do not push anything (must specify explicitly) |
| `current` | Push current branch to same-named remote branch |
| `upstream` / `tracking` | Push current branch to its upstream |
| `simple` | Like `upstream` but refuse if branch names differ (default since Git 2.0) |
| `matching` | Push all branches that have same name on remote |
## Fetch
`git fetch` downloads objects and updates remote-tracking refs:
```bash
git fetch origin # Fetch all refs from origin
git fetch origin main # Fetch only main
git fetch origin refs/heads/main:refs/heads/main # Fetch into local branch
git fetch --prune origin # Delete stale remote-tracking refs
git fetch --all # Fetch from all remotes
git fetch --depth=1 origin # Shallow fetch
git fetch --unshallow # Convert shallow to full clone
```
### Fetch Head
After a fetch, `.git/FETCH_HEAD` records the fetched tips:
```
abc1234def... branch 'main' of https://github.com/user/repo
567890abc... not-for-merge branch 'feature' of ...
```
Lines marked `not-for-merge` are informational. The unmarked line is what `git pull` would merge.
## Pull
`git pull` = `git fetch` + `git merge` (or `git rebase`):
```bash
git pull origin main # Fetch + merge
git pull --rebase origin main # Fetch + rebase
git pull --ff-only # Only if fast-forward
```
### Pull Rebase
```bash
git config pull.rebase true # Always rebase on pull
git config pull.rebase merges # Rebase with --rebase-merges
git config pull.ff only # Only fast-forward
```
## Push
`git push` uploads objects and updates remote refs:
```bash
git push origin main # Push main
git push -u origin main # Push and set upstream
git push origin --all # Push all branches
git push origin --tags # Push all tags
git push origin --follow-tags # Push annotated tags reachable from pushed refs
git push origin --delete feature # Delete remote branch
git push origin :feature # Delete remote branch (old syntax)
```
### Force Push
```bash
git push --force origin main # Overwrite remote history (dangerous)
git push --force-with-lease origin main # Force push with safety check
git push --force-with-lease=main:abc123 # Force push only if remote is at abc123
```
`--force-with-lease` checks that the remote ref is at the expected value before overwriting. This prevents overwriting someone else's push.
### Push Options
```bash
git push -o ci.skip # Send push option to server
git config receive.advertisePushOptions true # Server-side: advertise support
```
Push options are passed to `pre-receive` and `post-receive` hooks on the server.
## Transfer Protocols
Git supports several protocols for remote communication:
### Local Protocol
```
git clone /path/to/repo.git
git clone file:///path/to/repo.git
```
- Without `file://`: Uses hard links or local copy (fast, no protocol)
- With `file://`: Uses the smart HTTP protocol over a pipe (slower, but validates like a remote)
### HTTP/HTTPS Protocol
```
https://github.com/user/repo.git
```
Two variants:
| Variant | Description |
|---------|-------------|
| **Dumb HTTP** | Static file serving — no server-side Git. Fetches loose objects and packs directly. No push. |
| **Smart HTTP** | Server runs `git-http-backend`. Supports fetch and push. Negotiation over HTTP. |
Smart HTTP uses `git-http-backend` as a CGI program. The client sends a `GET /info/refs?service=git-upload-pack` (fetch) or `GET /info/refs?service=git-receive-pack` (push) to start negotiation.
### SSH Protocol
```
git@github.com:user/repo.git
ssh://user@host/path/to/repo.git
```
SSH runs `git-upload-pack` (fetch) or `git-receive-pack` (push) on the remote host. The protocol is the same as the smart pack protocol, tunneled over SSH.
### Git Protocol
```
git://host/path/to/repo.git
```
A custom, unauthenticated protocol using `git-daemon`. Read-only by default. Rarely used today due to lack of authentication.
## Pack Protocol (Smart Protocol)
The smart protocol is used by SSH, smart HTTP, and the git protocol. It has two phases:
### Fetch (Upload Pack)
```
Client Server
│ │
├── GET /info/refs?service=git-upload-pack ──►
│ │
│◄── ref advertisement (refs + capabilities) ──┤
│ │
├── want <OID> (of each ref to fetch) ─────────►
├── have <OID> (of objects client has) ────────►
│ │
│◄── ACK/NAK (negotiation) ────────────────────┤
│◄── packfile data ────────────────────────────┤
```
1. **Reference advertisement**: Server lists all refs and their OIDs
2. **Negotiation**: Client sends `want` lines for desired refs and `have` lines for objects it already has
3. **Pack transmission**: Server sends a thin packfile containing only the objects the client needs
### Push (Receive Pack)
```
Client Server
│ │
├── GET /info/refs?service=git-receive-pack ──►
│ │
│◄── ref advertisement + capabilities ────────┤
│ │
├── packfile data ─────────────────►│
├── update ref commands ───────────►│
│ │
│◄── report status ────────────────┤
```
1. **Reference advertisement**: Server lists refs and capabilities
2. **Pack transmission**: Client sends a thin packfile with new objects
3. **Ref update**: Client sends ref update commands (`<old-oid> <new-oid> <ref>`)
4. **Report**: Server reports success/failure for each ref update
## Credential Helpers
Git delegates credential storage to external helpers:
```bash
git config credential.helper cache # In-memory cache (15 min default)
git config credential.helper cache --timeout=3600 # 1 hour
git config credential.helper store # Store in ~/.git-credentials (plaintext)
git config credential.helper osxkeychain # macOS Keychain
git config credential.helper manager # Windows Credential Manager
git config credential.helper libsecret # Linux libsecret
```
### Custom Credential Helpers
```bash
git credential fill # Prompt for credentials (stdin protocol)
git credential approve # Store credentials
git credential reject # Discard credentials
```
The credential helper protocol uses key-value pairs on stdin/stdout:
```
protocol=https
host=github.com
username=user
password=secret
```
## Shallow Clones
Shallow clones truncate history at a certain depth:
```bash
git clone --depth 1 <url> # Only the latest commit
git clone --depth 1 --single-branch <url> # Only one branch
git clone --shallow-submodules <url> # Shallow submodules too
```
### Shallow File
`.git/shallow` lists the commit OIDs at the shallow boundary:
```
abc1234def567890...
567890abcdef1234...
```
Commits below the shallow boundary are not present. Some operations are limited:
- `git log` cannot show history beyond the shallow point
- `git push` from a shallow repo may be rejected (server config `receive.denyShallowCommits`)
- `git fetch --unshallow` converts to a full clone
## Mirror Clones
```bash
git clone --mirror <url>
```
A bare clone that:
- Fetches all refs (including refs outside `refs/heads/` and `refs/tags/`)
- Sets `remote.origin.fetch = +refs/*:refs/*`
- Sets `remote.origin.mirror = true`
- Sets `remote.origin.prune = true`
## Edge Cases and Known Issues
- **Force push safety**: `--force-with-lease` is not foolproof — if you fetched but didn't integrate, the expected value may be stale.
- **Shallow clone limitations**: Many operations (blame, log, bisect) are limited or broken with shallow clones. Use `--unshallow` to convert.
- **Credential storage**: `credential.helper store` stores passwords in **plaintext**. Use OS-native helpers instead.
- **Push to non-bare**: Pushing to a non-bare repository can cause the working tree to diverge from HEAD. The receiving repo should be bare or use `receive.denyCurrentBranch = refuse`.
- **Refspec ordering**: When multiple refspecs match the same destination, the last one wins.
- **Large repos**: For very large repositories, partial clone (`--filter=blob:none`) and sparse-checkout can dramatically reduce initial download size.
## References
- <https://git-scm.com/docs/git-remote>
- <https://git-scm.com/docs/gitprotocol-pack>
- <https://git-scm.com/book/en/v2/Git-on-the-Server-The-Protocols>
## Related Skills
- For reference types and refspecs, see [refs.md](refs.md)
- For packfile format, see [objects.md](objects.md)
- For partial clone and sparse-checkout, see [worktree.md](worktree.md)
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |