Skip to content

Working with Remotes in Git

So far, we've mostly focused on using Git locally. However, a major strength of Git is its ability to facilitate collaboration through remote repositories. This page covers how to interact with these remotes.

Prerequisites: Understanding of Git basics and core concepts like branching and merging (Introduction, Core Concepts).

What are Remote Repositories?

A remote repository (or "remote") is simply a version of your project hosted somewhere else, typically on the internet or a network server. You can have multiple remotes, but often you'll have one primary remote that acts as a central point for collaboration.

  • Purpose:
    • Collaboration: Allows multiple developers to share code and contribute to the same project.
    • Backup: Provides an offsite copy of your project history.
    • Integration: Platforms hosting remotes often provide additional tools (issue tracking, CI/CD, code review).
  • Hosting Platforms: Popular platforms for hosting remote Git repositories include GitHub, GitLab, and Bitbucket.

Managing Remotes

You interact with remotes using the git remote command.

  • Adding a Remote: Connect your local repository to a remote one. 
    # Syntax: git remote add <shortname> <url>
git remote add origin [https://github.com/your-username/your-repo.git](https://github.com/your-username/your-repo.git)
    • <shortname>: A local alias for the remote URL (conventionally origin for the primary remote).
    • <url>: The URL of the remote repository (usually found on the hosting platform).
  • Viewing Remotes: See which remotes are configured. 
    git remote -v
    This shows the shortname and URL for fetch and push operations.
  • Renaming a Remote: 
    git remote rename <old-name> <new-name>
  • Removing a Remote: 
    git remote remove <shortname>

Getting Changes from a Remote: Fetching and Pulling

To update your local repository with changes from a remote:

  • `git fetch <remote-name:
    • Downloads commits and objects from the remote repository that you don't have locally.
    • Updates your remote-tracking branches (e.g., origin/main). These are local pointers to the state of the branches on the remote the last time you fetched.
    • Crucially, git fetch does NOT modify your local working directory or your local branches (like main). It just gets the data.
    • Useful to see what has changed on the remote before deciding how to integrate it.
  • git pull <remote-name> <branch-name>:
    • Essentially performs a git fetch followed by a git merge (or git rebase, if configured).
    • It fetches changes from the specified remote branch and immediately tries to integrate them into your current local branch.
    • Example: If you are on your local main branch, git pull origin main fetches origin/main and merges it into your local main.
    • This is a common way to update your local branch, but be aware it triggers an immediate merge (which might result in conflicts).

Sending Changes to a Remote: Pushing

Once you have committed changes locally, you can share them by pushing them to a remote.

  • git push <remote-name> <local-branch-name>:<remote-branch-name>:
    • Uploads your local branch commits to the specified remote branch.
    • Often simplified to git push <remote-name> <branch-name> if the local and remote branch names are the same.
    • Example: git push origin main pushes your local main branch to the main branch on the origin remote.
  • Setting Upstream: The first time you push a new local branch, you might use the -u flag: 
    git push -u origin feature-branch
    This sets up a tracking relationship between your local feature-branch and origin/feature-branch. After this, you can often just run git push (and git pull) from that branch without specifying the remote and branch names.
  • Push Rejection: Git will prevent you from pushing if the remote branch has commits that you don't have locally (i.e., the histories have diverged). You need to pull (or Workspace and merge/rebase) the remote changes first, integrate them with your local changes, and then push.

Cloning: Getting Started with a Remote Project

If a project already exists on a remote server, the easiest way to get a local copy is to clone it.

  • git clone <repository-url>:
    • Creates a full copy of the remote repository on your local machine.
    • Automatically sets up the original URL as the origin remote.
    • Checks out the default branch (usually main or master).

Collaboration Workflows

Remotes enable various team workflows. Two common patterns are:

  • Feature Branch Workflow:
    1. Create a new branch locally for each feature or bug fix.
    2. Develop and commit changes on that branch.
    3. Push the feature branch to the remote repository.
    4. Open a Pull Request (PR) or Merge Request (MR) on the hosting platform (GitHub/GitLab). This is a formal request to merge your feature branch into the main branch, allowing for code review and discussion before merging.
    5. Once approved, the branch is merged (often via the web interface).
  • Forking Workflow: (Common in open-source)
    1. Create a personal copy (fork) of the main repository on the hosting platform.
    2. Clone your fork locally.
    3. Create feature branches, commit, and push to your fork.
    4. Open a Pull Request from your fork's branch back to the original repository.

Interacting with remotes is fundamental for collaborative development and backing up your work. Mastering Workspace, pull, push, and understanding workflows like Pull Requests is essential.