Remote Repositories, part 2: Remote Branches
When working with a remote repository, for every local branch there is a corresponding remote tracking branch named <remote_name>/<local_Git_branch_name> (e.g., origin/master). Similar to how local branches keep track of commits in the local Git system, remote branches track commits submitted to the remote repository. We can check the list of branches using the following three commands:
git branch : shows the branches in the local machinegit branch –r : shows the branches in the remote repositorygit branch –a : shows all (local and remote) branches
Remote branches can be a bit conceptually tricky, especially in combination with indirect remote collaboration (forking). To help illustrate these concepts, the rest of this section simulates a remote collaboration scenario and shows how the branches change during the process.
We’ll start from the very first step of working with remote repositories: registration.
After making an account and creating a repository, the next thing is to commit some changes to the repository. In this scenario, the first commit adds a README file. This automatically creates a branch named master in the remote repository.
To transfer the Git commit history to a local repository (hosted on our local machine), we use the git clone command. In addition to copying the entire commit history, when a repository is cloned from a remote host a new entity is created called a remote tracking branch. This feature plays the role of an ambassador to the remote repository from the local one and points to the last commit from the remote repository in the Git tree. The remote tracking branch continues to move and point to subsequent commits that are made only to the remote repository. This means that new commits can be made in the local repository while the remote tracking branch still points to the last commit in the remote repository.
In the next step, we make a new commit in the remote repository.
Then, we fetch the changes into our local repository. This operation moves the remote tracking branch, however, the HEAD in the master branch is still pointing to the first commit.
In order to update the HEAD in the local repository, we can use git merge origin/master. We could also use git pull <remote_name> instead of git fetch <remote_name> and then git merge <remote tracking branch>; however, it is recommended to stick to using separate fetch and merge commands as it can help to avoid some unexpected merge results.
Next, we make a new commit to the local repository, which moves the HEAD in the local master branch to the last commit. This does not affect the remote tracking branch (on GitHub/GitLab/another remote repository platform).
To reflect these changes and add our commits to the remote repository, we need to use git push <remote_name> <branch_name>. Now, the remote tracking branch is updated and the new commit(s) will be copied into the remote repository.
As explained before, using remote repositories within Git facilitates collaboration between multiple developers. If all the collaborators are members of the project hosted on GitHub or GitLab, they can each contribute to project development simply by pulling and pushing changes between their local copies of the repository and the remote. However, if someone who is not a project member wishes to contribute to a public project, the collaboration method changes (requires “forking”) and becomes a bit more complicated. In the same vein, tracking branches can also be a bit puzzling. Here we continue our scenario-based approach and show branch tracking in the forking process. Imagine user_A who is not part of a project¹, wants to add a feature to it. She should first fork that project into her user account in the remote repository platform. After that, she can clone the forked repository onto her local machine.
Let’s say user_A also wants to keep the local repository in sync with the original one. To do this end, user_A should make a remote copy (let’s call it upstream) of the original repository using git remote add <remote_name> <remote_url>. After establishing the connection, to add a remote tracking branch from the original remote repository, user_A should run git fetch upstream. Meanwhile, user_X makes a new commit locally and then pushes to the remote repository.
After making the commit c4, user_X pushes the changes to the remote repository.
Imagine it’s been a while since the last time user_A opened the project. Her current local repository is probably out of sync. To get all the new updates from the original remote repository, user_A runs git fetch upstream. This command will update the history of commits and the remote tracking branch of the upstream remote².
To sync the HEAD in the master branch, user_A runs git merge upstream/master. To update remote tracking branch of the remote origin, she runs git push origin master.
At some point, user_A creates a new branch called edit-2 in her local repository and makes a new commit to it.
After creating the branch, switching to it, and committing the new feature, her local and remote repositories can become synced using the git push origin edit-2 command.
After syncing the forked repository, one step remains: making the pull request. To do this, user_A goes to the remote repository URL and chooses the edit-2 branch from the drop-down menu at the top of the page. She then clicks on the new pull request button to request to merge her edit-2 branch into the master branch of the original repository’s master branch. If user_X (the owner of the original repository) approves the pull request, then the edit-2 new branch can be merged into the master branch in the remote repository and the forked and local copies should be re-synced afterward with the original remote repository.
Footnotes
- Let’s imagine this project is hosted in the repository_X and is managed by user_X.
- Please note that the HEAD of the master branch and remote tracking branch for the origin remote are out of sync.
