git-remote

List existing remotes with their names and URLs

$ git remote [[-v|--verbose]]

$ git remote show [remote_name]

$ git remote add [remote_name] [remote_url]

$ git remote set-url [remote_name] [new_url]

$ git remote get-url [remote_name]

$ git remote remove [remote_name]

$ git remote rename [old_name] [new_name]

git remote [-v | --verbose]
git remote add [-t <branch>] [-m <master>] [-f | --no-tags | --mirror=<fetch|push>] <name> <url>
git remote rename <old> <new>
git remote remove <name>
git remote set-head <name> (-a | --auto | -d | --delete | <branch>)
git remote set-branches [--add] <name> <branch>...
git remote set-url [--push] <name> <newurl> [<oldurl>]
git remote get-url [--push] [--all] <name>
git remote show [-n] <name>
git remote prune [-n | --dry-run] <name>
git remote update [-p | --prune] [<group> | --all]

-v | --verbose
    Be more verbose; show remote URLs when listing remotes.

add <name> <url>
    Adds a remote named <name> for the repository at <url>.

-t <branch>
    When adding, track only <branch> (and its symlinks) from the remote.

-m <master>
    When adding, set the remote's HEAD (default branch) to <master>.

-f
    Immediately run git fetch on the new remote after adding it.

--no-tags
    When adding with -f, do not fetch tags along with the remote.

--mirror=<fetch|push>
    Sets up a mirror of the remote for either fetching or pushing.

rename <old> <new>
    Renames the remote named <old> to <new>.

remove | rm <name>
    Removes the remote named <name>.

set-head <name> <branch>
    Sets the default branch (HEAD) for the remote to <branch>.

set-head <name> -a | --auto
    Auto-detects and sets the remote's HEAD to its default branch.

set-head <name> -d | --delete
    Deletes the configured default branch for the remote.

set-branches <name> <branch>...
    Changes the list of branches tracked for the remote. Replaces existing list.

set-branches --add <name> <branch>...
    Adds the specified branches to the list of branches tracked for the remote.

set-url <name> <newurl> [<oldurl>]
    Changes the URL for the remote <name>. If <oldurl> is specified, only that specific URL is changed if multiple exist.

set-url --push <name> <newurl> [<oldurl>]
    Changes the push URL for the remote <name>.

get-url <name>
    Retrieves the fetch URL for the remote <name>.

get-url --push <name>
    Retrieves the push URL for the remote <name>.

get-url --all <name>
    Retrieves all URLs (fetch and push) for the remote <name>.

show <name>
    Displays detailed information about the remote <name>.

show -n <name>
    Displays information about the remote <name> without fetching remote heads or tags.

prune <name>
    Deletes all stale remote-tracking branches for <name> (i.e., branches that no longer exist on the remote).

prune -n | --dry-run <name>
    Shows which remote-tracking branches would be removed by prune, without actually removing them.

update [<group> | --all]
    Fetches updates for a specified remote group or all remotes.

update -p | --prune [<group> | --all]
    Fetches updates and prunes stale remote-tracking branches for a specified remote group or all remotes.

git-remote is a Git porcelain command used to manage the set of remote repositories whose branches you track. Remotes are essentially aliases for repository URLs, making it easier to interact with other repositories. This command allows you to add new remotes, rename existing ones, remove them, change their URLs, and inspect their details. It's fundamental for collaborative workflows, enabling you to fetch, push, and pull changes from designated remote locations like GitHub, GitLab, or an internal server. It integrates closely with other Git commands like fetch, push, and pull. Understanding how to manage remotes is crucial for effective version control in a distributed environment, providing the necessary framework to interact with other contributors' work.

Adding a remote with git remote add only registers the remote; use git fetch <name> or git pull to retrieve its content. Removing a remote with git remote remove does not automatically delete corresponding local remote-tracking branches; these must be cleaned up manually (e.g., using git remote prune or git branch -d -r). Be cautious with the --mirror option as it significantly changes how Git interacts with the remote, making the local repository a bare clone.

git remote implicitly manages "remote-tracking branches" (e.g., origin/main). These are local references to the state of branches on a remote repository. They serve as a snapshot of the remote's state at the last git fetch or git pull operation, allowing you to examine remote changes without merging them into your local branches.

A remote can have separate URLs configured for fetching from it and pushing to it. By default, both operations use the same URL. However, git remote set-url --push allows configuring distinct URLs, which is useful in advanced scenarios such as fetching from a public mirror but pushing to a private, authenticated repository, or interacting with a CI/CD system.

git-remote has been a fundamental part of Git's architecture since its early days, essential for its distributed version control model. Its subcommands have been refined and extended over time to provide more granular control over remote interactions, adapting to complex collaborative workflows and diverse repository hosting environments. It remains a core utility for managing remote connections within a Git repository.

git-fetch(1), git-push(1), git-pull(1), git-branch(1), git-config(1)