Home
Getting Started
Dev Resources
Community
Sign up / Login

Github Tutorial

Introduction to Git

1. Getting Started
2. Clone
3. Pull

Project Management

4. Branch
5. Commit and Push
6. Pull Requests and Merge

Additional Items

7. Fork
8. Conclusion

Getting Started with Git

Git is a powerful tool for programmers which enables the large scale projects we create today. In summary, git allows an arbitrary number of programmers to view and contribute to a single codebase in an effective parallel fashion.

The installation and usage of git can vary slightly depending on what platform you are working on. This tutorial attempts to cover these differences as best as possible. For now, let's begin with the installation of git:

Windows: GitHub has created a website specifically aimed at bringing git to the Windows platform. Unlike Mac and the Linux flavors, the easiest way to install git is by vising GitHub's gitforwindows and downloading the provided .exe file.
Mac: Installing git onto a Mac is very straightforward. Simply open terminal and query git for it's current version using git --version. If git is not installed, it will ask if you'd like to install it.
Linux: Debian based distributions of Linux can have git installed using sudo apt install git-all; RPM-based distributions of Linux like Fedora, RHEL, and CentOS will instead use sudo dnf install git-all

After git has been installed on your system, Mac and Linux users can use the terminal to execute the other commands which are in this tutorial. Windows users should open a program called Git Bash; this will open a bash terminal in which you will be able to use the commands we discuss in this walkthough as well as many other basic bash commands (ls, cd, and others).

Clone

The first step to working on a repository is to get a local copy of it on your machine. In git, this is accomplished with the clone command. When run, the clone command will download the contents of a given repository onto your computer into the folder specified and mark that folder as the 'master'.

Using the terminal or Git Bash, the cloning a respository is very easy. Here are the basic steps to follow

Using cd, navigate to the directory where you want the repository to be located. For this tutorial, let's assume you have already created a folder called repositories in your home folder.
cd ~/repositories
Clone the repository by using the clone command.
git clone <link to repository> <directory to put it in>
Example: git clone https://github.com/uvalib/rotunda rotunda
At the end of this process, these commands will have created a rotunda folder inside of a repositories folder.

After these commands are run, you will have cloned the contents of the rotunda repository into ~/repositories/rotunda/

Note: we told git to place the contents of the repository into a directory with the same name as the GitHub repository. This is not required, but may help you to keep track of which repositories are which if you have cloned several.

Pull

When working in a repository with other people or on other machines, the time will come where the contents of the repository you have on your machine are out of date. The best example of this is cloning a repository which is used for a class. In order to have access to the newly added homework assignments or to have the latest version, you'd have to update your local copy of the repository.

If the repository you are working out of is public, all you need to do is use cd to navigate to the base directory of the repository and type git pull into Git Bash or terminal.

In the case that you're working from a private or protected repository, you may be asked to give credentials. In terminal, you'll likely be asked to enter the credentials directly each time you request access to the repository (pushes, pulls, etc); on Windows, Git Bash may store your credentials so they don't have to be typed in every time.

Storing Credentials

As stated above, sometimes the terminal will not store credentials, which means you will have to supply a username and password every time you use push or pull with a private or protected repository. To enable credential storing, try inputting the following command: git config credential.helper store.

Branch

Branching is one of the key elements of git and source control management in general. It is sort of like a classmate bringing three copies of their essay to class and having three of their peers each take one home to read through and edit at the same time. In the simplest terms, branching is used to separate and isolate changes to the source project.

When first getting to know good git practices, branching can seem a little unnecessary. Make sure you know why it's important. Here's a few reasons branching is good practice:

Minimally Viable Product (MVP): The master branch (the default one) should always have working code in it. When working to add a feature to your code, you should create and checkout a branch and work on it there. By commiting and pushing changes (we'll cover those in the next part of the tutorial) to the new branch, you'll maintain the original working product in the master branch. When you've completed you're feature and are ready to officially add it to the project, the two branches will be merged and any changes will be pushed into the master branch (see the next parts of the tutorial for more detail on how that works).
Keep Master Ready for Changes: Imagine you're working on adding a feature and it is only 50% done, so it's currently not working. Next, one of your collegues asks you to style a page which they have just merged into master. If you're currently committing directly to master, you'll be forced to push your 50% working feature along with the changes your colleague has requested.
Don't Trap Yourself in a Corner: If you work directly out of the master branch and start making a change, bug fix, or adding a feature, you're locked into finishing it before you can commit and update the master. Working out of a branch allows you to put work into multiple different things without finishing them in any particular order. Work on bug fixes for a little bit, add some features, and merge each branch with the master when it's ready.

Using branch

To start a new branch, navigate to the project directory and, in terminal or Git Bash, type in git branch branch_name, where branch_name is what you want to name the branch.

Creating the branch will not set it as the active one, read below to see how to make it active.

To set your newly created branch as the one which you are committing and pushing your changes to, you'll need to "checkout" the branch. Use git checkout branch_name to do so. If you're using Git Bash, you'll notice how the (master) marker next to the current directly will change to (branch_name) to indicate the current active branch.

A quick shortcut: the two commands above can be put into one by doing git checkout -b new_branch, where new_branch is the name of the branch you want to create!

Commit and Push

Commit is the command which is used to make any changes you've made to the local repository known to git. Additionally, on a service like GitHub, provided commit messages and/or descriptions will appear next to files that have been affected by the commit, allowing you to easily browse through and see which edits from which users were applied to specific files. Before pushing changes you'll need to commit them (hopefully) with a commit message describing what you've changed. The format for this command is git commit -m "message". Although -m "message" is optional, it is strongly recommended.

Some tips on this command:

If you are creating and removing files from the repository, you'll probably have to do git add * before trying to commit changes. This will make file/folder additions and removals part of the commit.
Commit is that it will commit the changes to the currently checked out branch, so make sure you're using the correct one.
If some of your changed are not being staged in the commit (git will probably complain in the terminal), type git commit . and a text editor will open a file containing a list of staged changes. Lines beginning with pound are unstaged, so all you usually need to do is find the changes which are unstaged and remove the pounds.

Push

Push is one of the easier commands to use as there aren't too many options for how to use it. The main prerequisite is that you must have run a commit before pushing since push will move staged commits to the remote repository (which requires something to be staged). In a push you have a couple options about where to push to, such as the destination repository and the destination branch. Let's take a look at the syntax.

Push commands will be structured like this: git push destination_repo destination_branch.

destination_repo: Where you want the push to go. Usually this is simply "origin" since you want to push the changes to the same repo that you're working from. Sometimes working with external services like Heroku will require you to push to their repository, which would require you to use "heroku" as the destination_repo parameter for example.
destination_branch: Specifies which branch in the given destination repository the changes are to be pushed to. Generally speaking, you should probably push changes to the same branch which you're working from. If you were working out of a branch called "login" then you would use that in place of destination_branch.

Let's say I was working in a branch called "gui" where I had just added interface components, and I wanted to stage and commit my changes to my "gui" branch on GitHub:

git add *
git commit -m "added gui components"
git push origin gui

Note: sometimes when pushing to multiple different sources / origins, you could be required to add -u to the push command, making it git push -u destination_repo destination_branch

Pull Requests and Merge

How to use these commands in Git Bash and/or terminal will not be addressed as they are considered by many to be too complex for command line usage. Instead, we'll be taking a look at how to do these operations on the GitHub website. Other SCM software will have similar equivalents for the things we're discussing, but we're just going to stick with GitHub.

If you're working on a branch and you've pushed your changes up to GitHub, the repository's landing page should show the branch under the branches tab. From this screen, the various branches which have been created will have buttons on the right indicating their status. To start a pull request, click the "New pull request" button.

In the image above, we're looking at the branches tab of a GitHub repository. We can see each branch is labeled with "Open", "New Pull Request", "Merged", or (not pictured) "Closed". Let's quickly go over what each of those means:

Open: A branch which is currently in development (last action was not merging into master).
New Pull Request: Indicates the branch has commits and is elligible to request being pulled into master. Doesn't guarantee a lack of merge conflicts, just indicates the branch is some number of commits ahead of master.
Merged: The given branch's last action was being successfully merged into master.
Closed: A branch which has essentially been marked as no longer active. Closed branches are ones which are no longer being used but have not been deleted.

Fork

Forking is used to duplicate a repository. The astute reader may recognize that this is sort of already done by branching from the repository, which we covered earlier; however, using branching implies that the edits being made have the eventual intention of being merged back into the master branch of that repository. In short, forking is used when the forked version of the repository will be taking a different development path from the original and has no plans of being merged back.

A great example of when fork can be used effectively is with group projects. Given a shared repository which the group uses throughout development, each individual member may want at the end to "take home" a copy of the project. Since you may want to continue your own work on the project, branching alone isn't good enough, since you don't want to keep pulling and pushing to the group repository. By forking the repository, it makes your own full and complete copy of it. To make it as simple as possible, it creates a new master branch which you alone can push to.

On the GitHub website, any repository can be forked using the Fork button near the top right of the code view, next to the star button. Forking a private repository is not possible, since you must be viewing it first.

Conclusion and Best Practices

For those who got this far, you officially have GitHub skills. To make sure you got everything, let's go over a quick checklist of things you should be able to do:

I can...

Install and configure git, Git Bash, or another SCM tool
Clone a repository to a folder on my machine and pull changes from it
Start, checkout, commit, and push to any given branch in a repository
Create a pull request and merge branches into master
Take a repository and duplicate it for my own development purposes

If you still feel shaky about any of these tasks, revisit their tutorial sections and read through it again. Try following along in a repository of your own; then, to test your knowledge, try it again without the tutorial open. Git (and SCM as a whole) is a critical tool for software developers, and mastering it is one the most important things to do before getting into the industry.

Best Practices

To avoid merge conflicts as much as possible, operate in a cycle: pull, commit, push, merge.
Never try to push and/or merge without pulling first. You'll almost certainly have merge conflicts.