Simply put, a remote repository is one that is not your own. It can be another Git repository that’s on your company’s network, the internet, or even your local filesystem, but the point is that it’s a repository distinct from your my-git-repo project.
We’ve already seen how branches can streamline a workflow within a single repository, but they also happen to be Git’s mechanism for sharing commits between repositories. Remote branches act just like the local branches that we’ve been using, only they represent a branch in someone else’s repository.
This means that we can adapt our merging and rebasing skills to make Git a fantastic collaboration tool. Over the next few modules, we’ll be exploring various multi-user workflows by pretending to be different developers working on our example website.
For several parts of this module, we’re going to pretend to be Mary, the graphic designer for our website. Mary’s actions are clearly denoted by including her name in the heading of each step.
DOWNLOAD THE REPOSITORY FOR THIS MODULE
If you’ve been following along from the previous module, you already have everything you need. Otherwise, download the zipped Git repository from the above link, uncompress it, and you’re good to go.
First, Mary needs her own copy of the repository to work with. The DISTRIBUTED WORKFLOWS module will discuss network-based remotes, but right now we’re just going to store them on the local filesystem.
cd /path/to/my-git-repo cd .. git clone my-git-repo marys-repo cd marys-repo
The first two lines navigate the command shell to the directory above my-git-repo. Make sure to change /path/to/my-git-repo to the actual path to your repository. The git clone command copies our repository into marys-repo, which will reside in the same directory as my-git-repo. Then, we navigate to Mary’s repository so we can start pretending to be Mary.
Run git log to verify that Mary’s repository is in fact a copy of our original repository.
First off, Mary needs to configure her repository so that we know who contributed what to the project.
git config user.name "Mary" git config user.email firstname.lastname@example.org
You may recall from the first module that we used a –global flag to set the configuration for the entire Git installation. But since Mary’s repository is on the local filesystem, she needs a local configuration.
Use a text editor to open up the file called config in the .git folder of Mary’s project (you may need to enable hidden files to see .git). This is where local configurations are stored, and we see Mary’s information at the bottom of the file. Note that this overrides the global configuration that we set in THE BASICS.
Today, Mary is going to be working on her bio page, which she should develop in a separate branch:
git checkout -b bio-page
Mary can create and check out branches just like we did in our copy of the project. Her repository is a completely isolated development environment, and she can do whatever she wants in here without worrying about what’s going on in my-git-repo. Just as branches are an abstraction for the working directory, the staged snapshot, and a commit history, a repository is an abstraction for branches.
Let’s complete Mary’s biography page. In marys-repo, change about/mary.html to:
Again, we’re developing this in a branch as a best-practice step: our master branch is only for stable, tested code. Stage and commit the snapshot, then take a look at the result.
git commit -a -m "Add bio page for Mary" git log -n 1
The Author field in the log output should reflect the local configurations we made for Mary’s name and email. Remember that the -n 1 flag limits history output to a single commit.
Now, we can publish the bio page by merging into the master branch.
git checkout master git merge bio-page
Of course, this results in a fast-forward merge. We’ll eventually pull this update into my-git-repo once we stop pretending to be Mary. Here’s what Mary’s repository looks like compared to ours:
Notice that both repositories have normal, local branches—we haven’t had any interaction between the two repositories, so we don’t see any remote branches yet. Before we switch back to my-git-repo, let’s examine Mary’s remote connections.
Mary can list the connections she has to other repositories using the following command.
Apparently, she has a remote called origin. When you clone a repository, Git automatically adds an origin remote pointing to the original repository, under the assumption that you’ll probably want to interact with it down the road. We can request a little bit more information with the -v (verbose) flag:
git remote -v
This shows the full path to our original repository, verifying that origin is a remote connection to my-git-repo. The same path is designated as a “fetch” and a “push” location. We’ll see what these mean in a moment.
Ok, we’re done being Mary, and we can return to our own repository.
Notice that Mary’s bio page is still empty. It’s very important to understand that this repository and Mary’s repository are completely separate. While she was altering her bio page, we could have been doing all sorts of other things in
my-git-repo. We could have even changed her bio page, which would result in a merge conflict when we try to pull her changes in.
Before we can get ahold of Mary’s bio page, we need access to her repository. Let’s look at our current list of remotes:
We don’t have any (origin was never created because we didn’t clone from anywhere). So, let’s add Mary as a remote repository.
git remote add mary ../marys-repo git remote -v
We can now use mary to refer to Mary’s repository, which is located at ../marys-repo. The git remote add command is used to bookmark another Git repository for easy access, and our connections can be seen in the figure below.
Now that our remote repositories are setup, we’ll spend the rest of the module discussing remote branches.
As noted earlier, we can use remote branches to access snapshots from another repository. Let’s take a look at our current remote branches with the -r flag:
git branch -r
Again, we don’t have any. To populate our remote branch listing, we need to fetch the branches from Mary’s repository:
git fetch mary git branch -r
This will go to the “fetch” location shown in git remote -v and download all of the branches it finds there into our repository. The resulting branches are shown below.
Remote branches are always listed in the form / so that they will never be mistaken for local branches. The above listing reflects the state of Mary’s repository at the time of the fetch, but they will not be automatically updated if Mary continues developing any of her branches.
That is to say, our remote branches are not direct links into Mary’s repository—they are read-only copies of her branches, stored in our own repository. This means that we would have to do another fetch to access new updates.
The above figure shows the state of our repository. We have access to Mary’s snapshots (represented as squares) and her branches, even though we don’t have a real-time connection to Mary’s repository.
Let’s check out a remote branch to review Mary’s changes.
git checkout mary/master
This puts us in a detached HEAD state, just like we were in when we checked out a dangling commit. This shouldn’t be that surprising, considering that our remote branches are copies of Mary’s branches. Checking out a remote branch takes our HEAD off the tip of a local branch, illustrated by the following diagram.
We can’t continue developing if we’re not on a local branch. To build on mary/master we either need to merge it into our own local master or create another branch. We did the latter in BRANCHES, PART I to build on an old commit and in THE PREVIOUS MODULE to revive a “lost” commit, but right now we’re just looking at what Mary did, so the detached HEAD state doesn’t really affect us.
We can use the same log-filtering syntax from the previous module to view Mary’s changes.
git log master..mary/master --stat
This shows us what Mary has added to her master branch, but it’s also a good idea to see if we’ve added any new changes that aren’t in Mary’s repository:
git log mary/master..master --stat
This won’t output anything, since we haven’t altered our database since Mary cloned it. In other words, our history hasn’t diverged—we’re just behind by a commit.
Let’s approve Mary’s changes and integrate them into our own master branch.
git checkout master git merge mary/master
Even though mary/master is a remote branch, this still results in a fast-forward merge because there is a linear path from our master to the tip of mary/master:
After the merge, the snapshots from Mary’s remote branch become a part of our local master branch. As a result, our master is now synchronized with Mary’s:
Notice that we only interacted with Mary’s master branch, even though we had access to her bio-page. If we hadn’t been pretending to be Mary, we wouldn’t have known what this feature branch was for or if it was ready to be merged. But, since we’ve designated master as a stable branch for the project, it was safe to integrate those updates (assuming Mary was also aware of this convention).
To complement our git fetch command, we’ll take a brief look at pushing. Fetching and pushing are almost opposites, in that fetching imports branches, while pushing exports branches to another repository. Let’s take a look:
git branch dummy git push mary dummy
This creates a new branch called dummy and sends it to Mary. Switch into Mary’s repository to see what we did:
cd ../marys-repo git branch
You should find a new dummy branch in her local branch listing. I said that git fetch and git push are almost opposites because pushing creates a new local branch, while fetching imports commits into remote branches.
Now, put yourself in Mary’s shoes. She was developing in her own repository when, all of a sudden, a new dummy branch appeared out of nowhere. Obviously, pushing branches into other people’s repositories can make for a chaotic workflow. So, as a general rule, you should never push into another developer’s repository. But then, why does git push even exist?
Over the next few modules, we’ll see that pushing is a necessary tool for maintaining public repositories. Until then, just remember to never, ever push into one of your friend’s repositories. Let’s get rid of these dummy branches and return to our repository.
git branch -d dummy cd ../my-git-repo git branch -d dummy
An important property of git push is that it does not automatically push tags associated with a particular branch. Let’s examine this by creating a new tag.
git tag -a v2.0 -m "An even stabler version of the website"
We now have a v2.0 tag in my-git-repo, which we can see by running the git tag command. Now, let’s try pushing the branch to Mary’s repository.
git push mary master
Git will say her master branch is already up-to-date, and her repository will remain unchanged. Instead of pushing the branch that contains the tag, Git requires us to manually push the tag itself:
git push mary v2.0
You should now be able to see the v2.0 tag in Mary’s repository with a quick git tag. It’s very easy to forget to push new tags, so if it seems like your project has lost a tag or two, it’s most likely because you didn’t to push them to the remote repository.
Priyanka Vatsa is a Senior Content writer with more than five years’ worth of experience in writing for Mindmajix on various IT platforms such as Palo Alto Networks, Microsoft Dynamics 365, Siebel, CCNA, Git, and Nodejs. She was involved in projects on these technologies in the past, and now, she regularly produces content on them. Reach out to her via LinkedIn and Twitter.