mintlify__docs/git/remote.mdx

---
title: git remote
description: Manage set of tracked repositories
---

Manage connections to remote repositories.

## Syntax

```bash
git remote [options] [<command>] [<name>]
```

## Description

`git remote` lets you view, add, remove, and manage remote repositories. Remotes are versions of your repository hosted on servers that you can push to and pull from.

## Common usage

List remotes:

```bash
git remote
```

Show remote URLs:

```bash
git remote -v
```

Add a remote:

```bash
git remote add origin https://github.com/username/repo.git
```

## Options

<ParamField path="-v, --verbose" type="flag">
  Show remote URLs
  
  ```bash
  git remote -v
  ```
</ParamField>

## Subcommands

### add

Add a new remote:

```bash
git remote add <name> <url>
```

### remove

Remove a remote:

```bash
git remote remove <name>
```

### rename

Rename a remote:

```bash
git remote rename <old> <new>
```

### set-url

Change remote URL:

```bash
git remote set-url <name> <newurl>
```

### show

Show information about a remote:

```bash
git remote show <name>
```

## Examples

### View remotes

```bash
# List remote names
git remote

# List with URLs
git remote -v
```

Output:
```
origin  https://github.com/user/repo.git (fetch)
origin  https://github.com/user/repo.git (push)
```

### Add a remote

```bash
git remote add origin https://github.com/username/repo.git
```

### Add multiple remotes

```bash
git remote add origin https://github.com/username/repo.git
git remote add upstream https://github.com/original/repo.git
```

### Remove a remote

```bash
git remote remove origin
```

### Rename a remote

```bash
git remote rename origin upstream
```

### Change remote URL

```bash
# Switch from HTTPS to SSH
git remote set-url origin git@github.com:username/repo.git

# Switch from SSH to HTTPS
git remote set-url origin https://github.com/username/repo.git
```

### Show remote details

```bash
git remote show origin
```

Output includes branches, tracking info, and URLs.

## Common workflows

### Initial setup after git init

```bash
git remote add origin https://github.com/username/repo.git
git branch -M main
git push -u origin main
```

### Fork workflow

```bash
# Add original repo as upstream
git remote add upstream https://github.com/original/repo.git

# Fetch from upstream
git fetch upstream

# Merge upstream changes
git merge upstream/main
```

### Multiple remotes

```bash
# Add production remote
git remote add production https://git.example.com/repo.git

# Add staging remote
git remote add staging https://staging.example.com/repo.git

# Push to specific remote
git push production main
git push staging develop
```

## Remote naming conventions

### origin

Default remote name, typically your main repository:

```bash
git remote add origin <url>
```

### upstream

Common name for the original repository in fork workflows:

```bash
git remote add upstream <url>
```

### Custom names

Use descriptive names for multiple remotes:

```bash
git remote add github <url>
git remote add gitlab <url>
git remote add production <url>
```

## Inspecting remotes

### List remote branches

```bash
git branch -r
```

### Show remote details

```bash
git remote show origin
```

Shows:
- Remote URL
- HEAD branch
- Remote branches
- Local branches configured for `git pull`
- Local refs configured for `git push`

### Verify remote connectivity

```bash
git ls-remote origin
```

## Changing protocols

### HTTPS to SSH

```bash
git remote set-url origin git@github.com:username/repo.git
```

### SSH to HTTPS

```bash
git remote set-url origin https://github.com/username/repo.git
```

## Troubleshooting

### Remote not found

```bash
git remote -v
# Check if remote exists

git remote add origin <url>
# Add if missing
```

### Wrong URL

```bash
git remote set-url origin <correct-url>
```

### Authentication issues

```bash
# For HTTPS, update URL with token
git remote set-url origin https://token@github.com/user/repo.git

# For SSH, ensure keys are set up
ssh -T git@github.com
```

### Prune stale remote branches

```bash
git remote prune origin
```

Removes references to deleted remote branches.

## Best practices

- Use `origin` for your main remote
- Use `upstream` for forked repositories
- Use descriptive names for multiple remotes
- Use SSH for repositories you push to frequently
- Use HTTPS for public repositories
- Regularly prune stale branches
- Verify remote URLs after cloning

## Related commands

- [git clone](/git/clone) - Clone with automatic remote setup
- [git fetch](/git/fetch) - Download from remote
- [git pull](/git/pull) - Fetch and merge
- [git push](/git/push) - Upload to remote
- [git branch](/git/branch) - Manage branches