Created by: Stamati Morellas (morel137@umn.edu)
Created for: The RADLAB Team
- Overview
- Git Terminology
- Creating a GitHub Account
- Installing git on your machine
- Creating a local git repository
- Adding a file to your local repository
- Adding a file to the staging environment
- Creating a commit
- Creating a new branch
- Creating a new repository on GitHub
- Pushing a branch to GitHub
- Creating a pull request
- Getting changes from GitHub onto your computer
- Git Commands
- Create
- Show
- Update
- Publish
- Branch
- Resolve Merge Conflicts
- Summary
- Sources Cited
Git is a free, open-source, version control system for tracking changes in computer files and coordinating work on those files among multiple people. As a distributed revision control system, it is aimed at speed, data integrity, and support for distributed, non-linear workflows. As with most other distributed revision control systems, and unlike most client-server systems, every Git directory on every computer is a full-fledged repository with complete history and full version tracking abilities, independent of network access or a central server.
GitHub is a free, open-source, web-based hosting service for version control using Git. It is most useful for computer code, however it is possible to store all kinds of files on GitHub. It provides access control and many collaboration features such as bug tracking, feature request, task management, and wikis for every project.
This is a guide to assist you on how to integrate the use of git commands and the overall GitHub system into your workflow. You will learn about the GitHub essentials which include:
- terminology
- git commands
- repositories
- branches
- commits
- pull requests
These are a list of Git and GitHub specific terms that are commonly used.
The "blame" feature in Git describes the last modification to each line of a file, which generally displays the revision, author and time. This is helpful, for example, in tracking down when a feature was added, or which commit led to a particular bug.
A branch is a parallel version of a repository. It is contained within the repository, but does not affect the primary or master branch allowing you to work freely without disrupting the "live" version. When you've made the changes you want to make, you can merge your branch back into the master branch to publish your changes.
A check is a type of status check on GitHub.
A clone is a copy of a repository that lives on your computer instead of on a website's server somewhere, or the act of making that copy. With your clone you can edit the files in your preferred editor and use Git to keep track of your changes without having to be online. It is, however, connected to the remote version so that changes can be synced between the two. You can push your local changes to the remote to keep them synced when you're online.
A collaborator is a person with read and write access to a repository who has been invited to contribute by the repository owner.
A commit, or "revision", is an individual change to a file (or set of files). It's like when you save a file, except with Git, every time you save it creates a unique ID (a.k.a. the "SHA" or "hash") that allows you to keep record of what changes were made when and by who. Commits usually contain a commit message which is a brief description of what changes were made.
A contributor is someone who has contributed to a project by having a pull request merged but does not have collaborator access.
Your personal dashboard is the main hub of your activity on GitHub. From your personal dashboard, you can keep track of issues and pull requests you're following or working on, navigate to your top repositories and team pages, and learn about recent activity in repositories you're watching or participating in. You can also discover new repositories, which are recommended based on users you're following and repositories you have starred. To only view activity for a specific organization, visit your organization's dashboard.
A diff is the difference in changes between two commits, or saved changes. The diff will visually describe what was added or removed from a file since its last commit.
Fetching refers to getting the latest changes from an online repository without merging them in. Once these changes are fetched you can compare them to your local branches (the code residing on your local machine).
A fork is a personal copy of another user's repository that lives on your account. Forks allow you to freely make changes to a project without affecting the original. Forks remain attached to the original, allowing you to submit a pull request to the original's author to update with your changes. You can also keep your fork up to date by pulling in updates from the original.
Git is an open source program for tracking changes in text files, and is the core technology that GitHub, the social and user interface, is built on top of.
Issues are suggested improvements, tasks or questions related to the repository. Issues can be created by anyone (for public repositories), and are moderated by repository collaborators. Each issue contains its own discussion forum, can be labeled and assigned to a user.
Markdown is a simple semantic file format, not too dissimilar from .doc, .rtf and .txt. Markdown makes it easy for even those without a web-publishing background to write prose (including with links, lists, bullets, etc.) and have it displayed like a website. Fun fact: This entire document is written in markdown!
Merging takes the changes from one branch (in the same repository or from a fork), and applies them into another. This often happens as a pull request (which can be thought of as a request to merge), or via the command line. A merge can be done automatically via a pull request via the GitHub web interface if there are no conflicting changes, or can always be done via the command line.
Open source software is software that can be freely used, modified, and shared (in both modified and unmodified form) by anyone. Today the concept of "open source" is often extended beyond software, to represent a philosophy of collaboration in which working materials are made available online for anyone to fork, modify, discuss, and contribute to.
Organizations are shared accounts where businesses and open-source projects can collaborate across many projects at once. Owners and administrators can manage member access to the organization's data and projects with sophisticated security and administrative features.
Private repositories are repositories that can only be viewed or contributed to by their creator and collaborators the creator specified.
Pull refers to when you are fetching in changes and merging them. For instance, if someone has edited the remote file you're both working on, you'll want to pull in those changes to your local copy so that it's up to date.
Pull requests are proposed changes to a repository submitted by a user and accepted or rejected by a repository's collaborators. Like issues, pull requests each have their own discussion forum.
Pushing refers to sending your committed changes to a remote repository, such as a repository hosted on GitHub. For instance, if you change something locally, you'd want to then push those changes so that others may access them.
This is the version of something that is hosted on a server, most likely GitHub. It can be connected to local clones so that changes can be synced.
A repository is the most basic element of GitHub. They're easiest to imagine as a project's folder. A repository contains all of the project files (including documentation), and stores each file's revision history. Repositories can have multiple collaborators and can be either public or private.
SSH keys are a way to identify yourself to an online server, using an encrypted message. It's as if your computer has its own unique password to another service. GitHub uses SSH keys to securely transfer information to your computer.
A status is a type of status check on GitHub.
Status checks are external processes, such as continuous integration builds, which run for each commit you make in a repository.
Teams are groups of organization members that reflect your company or group's structure with cascading access permissions and mentions.
When talking about a branch or a fork, the primary branch on the original repository is often referred to as the "upstream", since that is the main place that other changes will come in from. The branch/fork you are working on is then called the "downstream".
Users are personal GitHub accounts. Each user has a personal profile, and can own multiple repositories, public or private. They can create or be invited to join organizations or collaborate on another user's repository.
There are two kinds of accounts that can be used in GitHub, personal and enterprise accounts. The main difference between a personal and enterprise account is the ability to declare both public and private repositories in an enterprise account, as opposed to only having access to public repositories with a personal account. Everyone in RADLAB has access to an enterprise account, which can be accessed by logging in to https://github.umn.edu/ by using their university email and login.
Download Git from https://gitforwindows.org/ and install it.
Copy and paste the following command into a terminal window and hit Return.
ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"
brew doctor
You will be offered to install the Command Line Developer Tools from Apple. Confirm by clicking install. After the installation is finished, continue installing Homebrew by hitting Return again.
Copy and paste the following command into a terminal window and hit Return.
brew install git
You can now use Git!
Determine on which Linux distribution your system is based on. Most Linux systems (including Ubuntu) are Debian- based.
Open a terminal window, copy and paste the following command into the terminal window and hit Return. You may be prompted to enter your password.
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install git
You can now use Git!
Open a terminal window, copy and paste the following command into the terminal window and hit Return. You may be prompted to enter your password.
sudo yum upgrade
sudo yum install git
You can now use Git!
A repository (or repo for short) is usually used to organize a single project. Repositories can contain folders and files, images, videos, spreadsheets, and data sets – anything your project needs. We recommend including a README, or a file with information about your project. GitHub makes it easy to add one at the same time you create your new repository. It also offers other common options such as a license file.
To begin, open up Terminal and move to where you want to place the project on your local machine using the cd (change directory) command.
To initialize a git repository in the root of the folder, run the git init command.
Go ahead and add a new file to the project, using any text editor you like (I personally find Atom to be the best text editor, and it can be downloaded from https://atom.io/), or by running a touch command inside the terminal.
Once you've added or modified files in a folder containing a git repository, git will notice that changes have been made inside the repository. But, git won't officially keep track of the file (a.k.a put in a commit - we will talk more about this in the next section) unless you explicitly tell it to.
After creating the new file, you can use the git status command to see which files git knows exist.
Add a file to the staging environment using the git add command.
If you return the git status command, you'll see that git has added the file to the staging environment (or staging area).
To clarify, the file has not yet been added to a commit, but it is about to be.
Now it is time to create a commit.
Run the command git commit -m "Your message about the commit".
The message at the end of the commit should be something related to what the commit contains, which could be a new feature, a bug fix, or even something as simple as fixing a typo. It is important to provide constructive messages for the commit so that the other people that see the commit know what has been changed.
Now that you know how to make a commit, let's try something a little more advanced.
Let's say that you want to create a new feature in a file, but you are worried about making changes to the main project while developing the feature. This is where git branches come in very handy.
Branches allow you to move back and forth between "states" of a project. For instance, if you want to add a new page to your website, you can create a new branch just for that page without affecting the main part of the project. Once you're done with the page, you can merge your changes from your-branch into the master branch. When you create a new branch, Git keeps track of which commit your branch "branched" off of, so it knows the history behind all the files.
Let's say you are on the master branch and want to create a new branch to develop your web page. Here's what you have to do: Run git checkout -b <my branch name>. This command will automatically create a new branch and then "check you out" on it, meaning git will move you to that branch, off of the master branch.
After running the above command, you can use the git branch command to confirm that your branch was created.
The branch name with the asterisk next to it indicates which branch you're pointed to at that given time.
Now, if you switch back to the master branch and make some more commits, your new branch will not see any of those changes until you merge those changes onto your new branch.
So far in this tutorial, we have only covered things that will keep track of your code and other files locally.
If you only want to keep track of your files locally, you don't need to use GitHub. But if you want to work with a team (which in this case you should if you are a part of RADLAB), you can use GitHub to collaboratively modify the project's files.
To create a new repository on GitHub, log in (again, using https://github.umn.edu) and go to the GitHub home page. You should see a green "+ New repository" button.
After clicking the button, GitHub will ask you to name your repository and provide a brief description.
When you're done filling out the information, press the "Create repository" button to make your new repo.
GitHub will ask you if you want to create a new repo from scratch or if you want to add a repo you have created locally. In this case, since we've already created a new repo locally, we want to push that onto GitHub so follow the "....or push an existing repository from the command line" section (You'll want to change the URL in the first command line to what GitHub lists in this section since your GitHub username and repository name are different).
Important: The above information is great if you want to create your own local repository and store it on GitHub. However, for RADLAB, Dr. Cullen and I have created a GitHub organization for RADLAB Which can be found by going to https://github.umn.edu/RADLAB which is essentially a collection of repositories all related to different RADLAB projects. This is essentially where all the RADLAB files will be stored on GitHub in a rather organized manner. In order to work with this, you will need to have Dr. Cullen (or any other organization administrator) add you to the organization. If you are not yet a part of it, you can send Dr. Cullen or I an email and one of us will add you.
Stamati's email: morel137@umn.edu
Dr. Cullen's email: rega0026@umn.edu
Next, I will go over some steps on how you can get these repositories onto your machine and make your own changes by adding files and what not.
Assuming you've already managed to log in to https://github.umn.edu with your university credentials, head over to the organization page at https://github.umn.edu/RADLAB and click on the repository you wish to contribute to. I have created a repository for testing purposes so that you can practice creating a local version of this repository, adding and modifying files, and pushing the changes you make onto the master branch of this repo. You can find this repository at https://github.umn.edu/RADLAB/test. (The information below applies to any other repository in the RADLAB organization, but at first, try using it on the test repository before engaging with any of the others.)
After navigating to the test repository on the RADLAB organization page, look for the "Fork" button in the top right corner of the page and click it.
GitHub will now create a copy of the test project in your account and will give you read and write access to this copy.
Note: Your forked copy will not automatically update itself as the test project gets updated. Your forked copy represents the test project as it existed at the moment when you have forked it.
To stay up to date with the latest test repository changes, be sure to Watch and Star the repository from its github.umn.edu page. All updates will then appear in your personal news feed when you visit github.umn.edu
You are now ready to set up your local environment.
Start up Git Bash in the terminal.
Type in the following command:
git config --global user.name "Your name here"
This will be the name that shows up in the commits whenever you make a modification.
Next, type in this command:
git config --global user.email "your_email@domainname.com"
Make sure to enter the email address that is associated with your umn github account!
Now that your username and email are configured, it is time to clone the repository.
When you login to github.umn.edu on the web, you should see your repositories on the right-hand side of the screen. Navigate to your_user_name/test.
You should now see the files contained in your repository and the time since each file was last modified in the currently selected branch (Remember that this reflects the online repository, not your local changes).
Near the top of the screen, you will see the the repository URL. Copy this address to your clipboard and return to the gitbash (terminal).
By default, the command "git_clone_repository_name" will replace the directory structure of your forked repository whenever the default Git Config tells it to.
If you want to clone the repository somewhere else, simply add the pathname at the end of the command like this:
git clone repository_name /path/to/localrepository/
Now type in the following command to clone your forked repository into the directory dev/test on your E: drive.
git clone git@github.com:your_username/test.git /e/dev/test
You will see that GitBash will display the cloning's progress as it downloads the files. Once complete, head over to your chosen directory where you should see all the files!
When you first clone a repository, git will automatically create a remote named "origin" for you.
Now, remember that this remote will point to YOUR repository, which was forked from the official test repository. As mentioned before, over the course of development, the test repository will be updated but YOUR repository will not.
To remedy this, we want to setup a remote that will track the original repository test.
Using Git Bash, navigate to your project's directory. Once you are in the right place, you should see master appear after the current directory's name. This represents the currently active branch.
EVERY ACTION YOU TAKE WILL BE APPLIED TO THE CURRENTLY ACTIVE BRANCH.
Return to Git Bash and type in:
git remote add upstream https://github.com/RADLAB/test.git
This will add a new remote called "upstream" which points to the official RADLAB/test repository. If you want to see where each remote is pointing, type in:
git remote -v
Making changes directly to your master branch is a bad idea. You should always have a working branch to try out your modifications on.
To list the available branches for your current project, type in:
git branch
To create a new branch, naming it whatever you want, type in:
git branch branch_name
To delete a branch, type in:
git branch -D branch_name
To switch to a branch, making it the currently active branch, type in:
git checkout branch_name
As an example, in order to return to your master branch, you should type in:
git checkout master
Whenever you want to update your online repository with your local changes, you need to follow these basic steps:
git addall the new or modified files to your staging area- Execute a
git committo take a snapshot of your local staging area git pushthe snapshot to your online repository
Whether you have modified an existing file or created a new one in the local repo, the procedure remains the same.
Simply type in:
git add modified_filename1 modified_filename2 newly_created_filename1
This will add the specified files to your staging area.
If you do not call git add on a modified file, the staging area will simply keep the version of the file which existed when it was last added via git add.
You may also call:
git add .
This will add all modified or new files in your entire project to your staging area.
Once your staging area is ready, you must commit your changes by typing:
git commit -m 'Relevant message about this commit'
If you run git status or look at your project via github.umn.edu, you will see the messages of each commit next to the modified files as well as the date of the last commit.
Finally, you push your commit to your online repository by typing:
git push remote_name branch_name
or more specifically:
git push origin development
The above command will push the changes from your currently active branch to your online repository's development branch. You cannot push your commit to the upstream remote if you do not have access to the test repository, further, the RADLAB organization.
If you do not have write access to an online repository and want to push your changes to the upstream remote, you will need to submit a pull request, which will be talked about in a couple of the next sections.
Now, we'll push the commit in your branch to your new GitHub repo. This allows other people to see the changes you've made. If they're approved by the repository's owner (which is done by submitting a pull request), the changes can then be merged into the master branch.
To push changes onto a new branch on GitHub, you'll want to run git push origin yourbranchname. GitHub will automatically create the branch for you on the remote repository.
You might be wondering what that "origin" word means in the command above. What happens is that when you clone a remote repository to your local machine, git creates an alias for you. In nearly all cases this alias is called "origin." It's essentially shorthand for the remote repository's URL. So, to push your changes to the remote repository, you could've used either the command: git push git@github.com:git/git.git yourbranchname or git push origin yourbranchname
(If this is your first time using GitHub locally, it might prompt you to log in with your GitHub username and password.)
If you refresh the GitHub page, you'll see note saying a branch with your name has just been pushed into the repository. You can also click the "branches" link to see your branch listed there.
A pull request (or PR) is a way to alert a repository's owner(s) that you want to make some changes to their repository. It allows them to review the files and make sure it looks good before putting your changes on the master branch.
Note: Submitting a pull request is done by clicking the "New Pull Request" button on a repository's page on github.umn.edu/RADLAB and then proceeding from there. Once approved, there should be a green "Merge Pull Request" button, which means that your changes will be merged with the master branch.
Sometimes you'll be a co-owner or the sole owner of a repo, in which case you may not need to create a PR to merge your changes. However, it's still a good idea to make one so you can keep a more complete history of your updates and to make sure you always create a new branch when making changes.
Once you've clicked the "Merge Pull Request" button, I would recommend deleting your branch, as having too many branches can become messy, so hit the grey "Delete Branch" button as well.
You can double check that your commits were merged by clicking on the 'Commits' link on the first page of your new repo.
Right now, the repo on GitHub looks a little different than what you have on your local machine. For example, the commit you made in your branch and merged into the master branch doesn't exist in the master branch on your local machine.
In order to get the most recent changes that you or others have merged on GitHub, use the git pull origin master command (when working on the master branch).
This shows you all the files that have changed and how they've changed.
Now we can use the git log command again to see all new commits.
(You may need to switch branches back to the master branch. You can do that using the git checkout master command.)
Here is a collection of some of the most common git commands that you will need to use, as well as a short description of what they are used for.
git init - Initialize a new git project in your current working directory
git add <filename> - Add a file to the staging area
git clone <remote_location> <clone_name> - creates a local copy of a remote
git status - Check the status of the changes you've made in the current repository
git diff <filename> - Check the differences between the working directory and the staging area
git log - View the chronologically-stored commits in the repository
git show HEAD - Shows the head commit (the commit you're currently on)
git branch - Shows what git branch you are on
git branch <new_branch> - Creates a new branch named new_branch
git branch -d <branch_name> - Deletes the branch_name branch after it has been integrated into the master branch.
git fetch - Fetches work from the remote into the local copy.
git pull <repo_url> - Fetch from and integrate with another repository or a local branch
git commit -m "message" - Permanently stores the changes from the staging area inside the repository.
git push origin <branch_name> - Pushes a local branch to the original remote.
git checkout HEAD <filename> - Restores the file in your working directory to look exactly as it did when you last made a commit.
git checkout <branch_name> - Allows you to switch to a different branch named new_branch.
git merge <branch_name> - Merges the changes made to the branch_name branch with the master branch.
git reset HEAD <filename> - Resets the file in the staging area to be the same as the HEAD commit (it does not discard the file changes from the working directory, it just removes them from the staging area).
git reset <commit_SHA> - Enables you to "rewind" to before you made a mistake. Use the first 7 characters of the SHA of the previous commit.
Congratulations! You should now know how to navigate your way through GitHub, as well as use git commands inside the terminal. If you have any questions about how to do anything, feel free to send me an email at morel137@umn.edu and I will try my best to help you resolve your issues.
- https://en.wikipedia.org/wiki/Git
- https://gist.github.com/derhuerst/1b15ff4652a867391f03
- https://product.hubspot.com/blog/git-and-github-tutorial-for-beginners
- https://help.github.com/articles/github-glossary/
- https://guides.github.com/activities/hello-world/
- https://github.com/GarageGames/Torque2D/wiki/Cloning-the-repo-and-working-with-Git