📓 GitHub and Remote Repositories

GitHub is a website that allows us to easily store, track, and collaborate on coding projects. It is an incredibly popular site for developers to share code and collaborate with each other. Your GitHub account will be your coding portfolio. Most employers will want to see your GitHub profile to view your coding history and recent projects.

So as part of integrating Git into our workflow we need to learn how to store our coding projects on GitHub. Additional benefits to doing this include:

• We can access our projects from other devices.
• If something bad happens to our computer or to the .git repository in our project, we can retrieve our project from GitHub hopefully without much lost progress.

Overview

Git and GitHub naturally work in tandem. On your computer, you have a local version of your project stored in the .git repository. GitHub offers you remote repositories as a second place to store your project. Including GitHub into our Git workflow means we need to understand the relationship between the local and remote versions of our project.

Important new terminology:

• local
• remote
• push
• pull
• clone
• fork
• origin
• main branch

Exercise

We’re going to take an existing project with some commit history and push it to GitHub. To push to GitHub means that any additional commits in our local .git repository will be added to our remote repository on GitHub.

For example, let's say you made two commits in your project on your computer. You then push a copy of those commits to GitHub. Your project's history now exists in two places: in your local .git repository and in your remote repository on GitHub.

You keep working and over time make three more commits on your project on your computer. Your project's history in your local .git repository now looks different from the version of your project in your remote repository on GitHub. No problem, just push the changes from your local repository to your remote repository again. Now the two versions again match.

Where it gets complicated is when we collaborate with others. Say you’re on a team working with other people on the same project. Everyone has their own version of the project in their local .git repository on their own computer. However, everyone on the team is sharing the same remote repository on Github. This is intentional as part of how Git works as a version management system. Say you’re working on one task for the project but you can’t complete that task until your teammate completes their task. Your teammate completes the task but how do they then share that code with you? The answer is your teammate pushes their changes to the remote repository and then you pull those new changes from the shared remote repository to update your local repository. To pull means to get any content from a remote repository to update your local repository.

In a different scenario, you can also clone a remote repository from Github. To clone means to copy an existing remote repository to create a local repository on your computer. Similar to cloning a project, you can also fork a project. To fork a project is to copy an existing remote repository to your GitHub account.

By the end of this exercise, you should be able to:

1. Connect a remote repository to your local repository.
2. Push changes from a local repository to a remote repository.
3. Pull changes from a remote repository to a local repository.
4. Clone a project from GitHub
5. Fork a project on Github

Requirements:

Required you have a GitHub account created.

Project Setup:

This exercise assumes you have a project on your computer with some commit history. If not you can revisit the previous lessons on Git to create one.

The examples in this lesson will continue with the hello-world project started in very recent lessons.

Create a remote repository on Github

First thing we need to do is create a remote repository so we can later link it to our local repository.

1. Sign into your GitHub account, navigate to the “Repositories” menu and click “New” (Your Github theme may look different than ours):

2. You will be presented with a form to create a new repository. For now, all you need to do is give your repository a name. We have named ours “hello-world” but you may name yours whatever you like. Though, we recommend not to use spaces in your repository name. Instead use dashes - or underscores _.

Give your project a name, don’t touch any other settings, then click “Create repository” in the bottom right corner.

3. At this point, you’ve now created your remote repository! Your remote repository should look similar to the image below. This is what an empty remote repository looks like; meaning there is no project stored in it yet. We are going to do that next.

Copy the url to your remote repository by clicking the button circled in red in the image below. We’ll use this url to connect our remote repository to our local repository.

Connect a remote repository to a local repository

In your project's top level directory, use the git command:

git remote add origin the-url-to-your-remote-repo

The name “origin” is simply an alias in your local repository for a specific remote repository. By default, Github names your remote repository as “origin” but you can call it whatever you like.

The main reason you may want to rename “origin” to something else is that your local repository may be connected to several remote repositories. This often happens when working with others. Choosing a different nickname for a remote repository is as simple as replacing “origin” in the git command with something else. For example, my initials are “mtb” so I might do:

git remote add mtb a-different-url-to-a-remote-repo

The results are:

You only need to add a remote repository once per project. You can delete a connection to a remote repository by using the git command: git remote rm nickname-of-remote-repo.

Let's Pair Program!

If working remotely in a pair group: Only the person who has the project on their computer should connect to their remote repository at this time because only they have a local repository.

Everyone else in the pair group is working via VS Code Live Share. Everyone else in the pair group will get a copy of the project in their own GitHub account by forking which we'll talk about in this lesson.

If sharing a computer: Talk to an instructor about how your pair group should proceed. Epicodus computers will require some additional steps to set up your local Git configuration.

Push to a remote repository

Before you push your commit history from your local repository to your remote repository, make sure you actually have some commits to push. You can check by using git log. If needed, take a moment to create some new commits before proceeding.

In your project's top level directory, use the git command:

git push origin main 

Replace “origin” if you are using a different nickname for your remote repository. This git command means we should copy the changes from our local repository to a remote repository nicknamed “origin”, to the main branch. We will discuss in detail at a later time exactly what a branch is and how to utilize them. What you need to know now is that when you push changes you have to pick a branch and the main branch is the default in Git.

If successful, you should get a result like this:

Look back at your remote repository on GitHub, you should see something like this now:

You can view your commit history in your remote repository by clicking on the button highlighted with a red circle. Our example might have a different number of commits.

Good practice is to push your commit history to your remote repository when you are done working for the day or before a long break.

Pull from a remote repository

So far we know how to push changes on our local repository to our remote repository but how do we do the reverse? How to pull changes from a remote repository to our local repository?

We often need to pull when working with others using the same remote repository or when we make changes to our remote repository directly via GitHub. The latter is a common source of confusion for beginners to GitHub. Let's recreate that mishap and then fix it by using the git pull command.

1. In your remote repository on GitHub, click the “Add a README” button.

(READMEs is documentation for your project. We’ll talk more on READMEs later.)

2. Edit your project's README however you want and then click the “Commit changes” button (This page may look different than what is on your account):

3. A new form will appear, click the “Commit changes” button:

Going back to your remote repository, it should look something like this:

What have we done? We made a commit directly to our remoterepository via GitHub. We could have done the same process by creating a README.md file by touch README.md and making a commit on our local repository on our computer via the terminal.

Your remote repository should have one additional commit than your local repository at this time. If you were to try to push now then you would get an error message from Git like this:

Go ahead and try it yourself! Errors are fun! Thankfully, Git is providing us with a very helpful error message: “Updates were rejected because the remote contains work that you do not have locally…You may want to first integrate the remote changes (e.g., `git pull…) before pushing again.”

Git is telling us to pull our changes from the remote repository!

In the top level directory of your project, use the git command:

git pull origin main

The result should look something like this:

Using git log confirms you now have the additional commit(s) from your remote repository on your local repository.

Git requires that our remote and local repositories match before it will allow you to push changes. That is part of Git's role as a verison management system. Git enforces protocol for what to do when versions of our project don’t match so we don’t accidentally lose code when copying changes from one version to another.

Clone a remote repository

Okay, switching topics, let's say there is a remote repository that we don’t have on our computer but we want to copy it. To clone is to make a copy of a remote repository to be a local repository on our computer. You can clone any remote repository that is publicly available or that you have access to.

For example, let's clone the React library from Github; a tool we are going to use later in the program! React is created by Facebook(Meta) but is an open source tool. For us this means React's source code is freely available on GitHub.

Go to the website following the link above and click on the <> Code button then click on the copy button (circled in red with a 2):

Then, anywhere you are keeping projects on your computer, use the git command:

git clone url-of-remote-repo

A new folder called “react” should be created on your computer. You just created a copy of the “react” remote repository on your computer. This is now your local copy that you can do what you please with.

We picked the React repository to clone because we knew it would be readily available for this example on how to clone. However, typically you only need to clone remote repositories from your own GitHub account.

While you can clone a remote repository that doesn’t belong to you (in other words, it's not from your GitHub account), the problem in doing so is that you don’t have permission to push changes to remote repositories that live on other GitHub accounts. In our case, you need to be given permission from the owners of the react remote repository to push changes.

One way around this is to delete the connection between your copied local repository of react and the remote repository using `git remote rm nickname-of-repo-url.” Then create a new remote repository under your GitHub account and connect your copied local repository to react to your remote repository.

But that's a lot of confusing steps! The better solution is to fork.

Fork a remote repository

To fork a repository is to copy an existing remote repository to your GitHub account. It's very easy to do. Click the “Fork” button in a remote repository.

Click “create a new fork” and then select your account as the “Owner.”

That's it! Now you have your own copy of a repository from another GitHub account.

From here, you can clone and set up a connection to your remote repository as usual.

The original repository is known as the upstream repository. It is listed in your remote repository as “forked from…” There are a few paths you can take after forking a remote repository:

1. You want to take the project completely in your own direction. You are no longer interested in what the original repository is doing. This is totally fine to do but be sure to read the licensing information in the README of the original repository. Public repositories may still have terms of use. No matter what, never try to delete the commit history of a forked repository in your GitHub account. That's disrespectful to the original authors of the code and unethical.

Let's Pair Program!

If working remotely in a pair group: Option 1 above is recommended for pair groups working remotely. The person who has the original local repository on their computer will push to GitHub after a pair programming session is done.

Everyone else in the pair group will then fork a copy to their own GitHub accounts. When you are no longer pair programming with your peer on this project, you are free to take it any direction you please. For example, some students may put personal touches on their final copy of the project that will appear on their GitHub account or further implement something they couldn't do while pair programming.

You may have noticed that only one person in the pair group has been able to author commits. Don't worry, we are going to fix that soon so everyone gets credit for work.

2. You want your forked repository to be up to date with the original. In that case, use the “Sync fork” option in the image above (below the blue “Code” button). Any changes that happened in the original repository will be copied to your forked repository. People often do this because they are interested in contributing to the original repository. This is part of an advanced Git workflow for teams we will learn later.