# Getting to Know Git¶

by Dirk Colbry

Git is a version control system that is used by programmers all over the world. If you want to use programming then you should learn how to use git. This tutorial is just the first step in learning git. It is a complex tool with with a lot of functionality this tutorial tries to present only some of the commands based on what you nee to do. The three basic categories are:

1. Consumer of files (the class files)
2. Producers of files (your files)
3. Collaborators to files (code reviews)

Resources for these tutorials can be reviewed here:

Watch the following video for a brief overview of git and this tutorial:

## Installing Git¶

In order to effectively clone a directory you will need to install git on your computer.

How to install git will depend on the computer you are working on and it's operating systems. Many *nix based operating systems (Linux, MacOS, etc) may have git already installed. To check if git is installed open a command prompt on your system and type the following:

git --version


If git is installed you should see the version number. If not, you will get something like "Command not found error" If git is already installed you should be all set to go. If not, continue on with the remainder of the instructions.

For this tutorial we will assume that you already have conda Installed. The conda command is a cross-platform installation system. It is primarily installed with Anaconda Python distributions but has support for many other programming languages and commands (including git). Open up a command prompt on your system and see if you can run the following command:

conda --version


If conda is installed you should see it's version number if not try installing it from the Anaconda Python website.

Once you have conda working you should be able to install git using the following commands:

conda install git


That should be it. Test git again by opening the command prompt and typing git --version like we did above.

Although not required for using git, if you are using windows, I highly recommend also installing the md-base package which provides a nice set of *nix commands that will work on the windows command line. Many of these commands will be used in the demo videos so having them installed should help you follow along when you are watching the videos:

conda install m2-base


# Part one - Consuming Files¶

## Cloning a repository (Consumer)¶

Most people's introduction to git is when the come across some software on github.com they want to download. Downloading a git repository is called cloning. For example, lets download an example git repository called git_practice_repository using the following command:

git clone git_practice_repository


This should create a folder in your current directory with the name git_practice_repostory change into this directory using the following command:

cd git_practice_repository


List the contents of the directory using (dir on windows and ls on everything else)

A summary of the commands used in video:

git clone URL
cd FOLDER
ls
jupyter notebook


## Cleaning/Updating a cloned repository (Consumer)¶

It may be possible that the developer has made some changes to the repository and posted them on their git website. You can use the git pull command to pull in the changes to your repository.

git pull


Problems can occur if both you and the developer make changes to the same file. git is smart and can figure out how to automatically "merge" many changes but if there is a conflict you may have to figure out what to do. The easiest thing you can do is:

First, check to see what files are in conflict by running the get status command:

git status


You can look at the changes you made by running the git diff FILENAME command. This should show you what you added (Lines with a + before them) and what you deleted (lines with a - before them)

Once you have determined what you want to keep, make a copy of the file with a different name and then move on to the next step.

You can also reset (overwrite) all of the changes to your local files by "checking out" the original file. The git checkout FILENAME command gets a copy of the file file before your changes were made and overrides your changes.

git checkout FILENAME


Once all of the conflicts have been removed you can then go back and pull in the changes from the developer:

git pull


Review of commands used in video:

git fetch
git status
cp FILENAME BKUPFILENAME
git diff FILENAME
git checkout FILENAME
git pull


# Part two - Producing Files¶

Now that we are more familiar with git we can make your own repository. If you plan on using one of the web services such as Github or Gitlab (there are many others) then you can use their web interface to create a new project and then just clone the empty repository to your local machine. Often the web interfaces have some nice features to add some default files that are common in most repositories (ex. README.md and .gitignore)

However in this step we are going to assume that you have a directory with a few files already in it that you want to turn into a git repository. In this case you can just change to the git directory and issue the following git initialization command:

git init .


(Note: the dot in this command. It said to initialize the "current" directory and is very important to include)

Once you have successfully initialized the directory you can add files using the following commands (substitute these FILENAMES with yours):

git add FILENAME1 FILENAME2 FILENAME3
git commit -m "Initial commit"


WARNING git repositories work best with text based files.

Review of commands used in video:

git init .
git commit -m "DESCRIPTION"
git status


Here is a tutorial on how to create a new git repository using the MSU GitLab website:

Review of commands used in video:

git clone PROJECT
cat > FILENMAE
git status
git commit -m "DESCRIPTION"
git log
git push


Similarly, here is a tutorial on how to create a new git repository using the GitHub.com website:

Review of Commands used in video:

git clone URL
ls -lah
git status

Now that you have created a repository you want to get good at committing changes. It is important that modifications are committed early and often so that git can do what it does well and track your files. Committing files is a two step process.

1. First you want to use the git add FILENAME command to add new files or files you have changed to your "cart". Ideally the changes are related to each other.
git add FILENAME

1. Once all of the files have been added to your "cart" you can commit them by using the git commit -m "COMMIT MESSAGE" command. In this case the "COMMIT MESSAGE" is a note describing what you did. It is important that the note is a good description so you can find it later if you need it.
git commit -m "COMMIT MESSAGE"


Once you have committed your changes you may also want to issue a git push to push your changes up to the centralized repository (github or gitlab) as a safe backup and to share with your collaborators.

git push


Review of commands used in video:

ls
ls -lah
git log
cd FOLDERNAME
cat > NEWFILENAME
python NEWFILENAME.py
pytest NEWTESTFILE.py
cat status
vi FILENAME
fg
git commit -m "DESCRIPTION
git push


Branches are a powerful and important tool when using git. However, it amazes me how many people use git without ever touching branches. So, I guess you don't need them but once you understand how they work you can see their power and will find ways to use them all the time (sort of like git itself).

Branches are where you should do your work. Branches are a safe place to store changes to files. Anytime you want to change files you should make sure you are making and committing those changes to a branch.

To create a branch just type the following:

git branch BRANCHNAME


Once you have a branch you can list all of your branches (including the default "master" branch) and see which one you are on sing the following command:

git branch BRANCHNAME


To switch between branches just use the git checkout command with the BRANCHNAME:

git checkout BRANCHNAME


Review of commands used in video:

git status
git pull
ls
ls -lah
clear
git branch
git branch BRANCHNAME
git checkout BRANCHNAME
vi FILENAME
cat > NEWFILENAME
git commit -m "DESCRIPTION"


## Pulling in a new branch¶

So now we have two branches. The master branch has all of the changes made by the primary developer (ex. the instructor). The second branch has a name you provide ("Test" in this video). This secondary branch is where you do all of your work and commit your changes. Now you want to update your branch with changes from the master. To do this we just need to run the git merge command and fix any conflicts.

Review of commands used in video:

git branch
cat > NEWSFILENAME
vi FILENAME
git push
git pull
ls
cat FILENAME
cat NEWFILENAME
git checkout BRANCH
git merge origin master


## Resolving conflics in Jupyter Notebooks¶

Jupyter notebooks can be tricky to merge since it is in a JSON file format that gets changed each time you run the file which causes git to think you changed the file.

git
git checkout FILENAME
git status


# Part three - Collaborating¶

Up until now we have been mostly consumers or primary developers of our git repository. Now we want to think about how give some of our changes to other developers and be part of a community of software developers. The goal being actual collaboration without getting into each other's way.

## Issuing a pull/merge request¶

The idea is that we package up all of our suggested changes inside a branch and then "send" that branch to the lead developers for review. If they like what they see they can pull or merge (two words to basically mean the same thing) our branch into their master branch. This process has been given the name "pull request" or "merge request" depending on what system you are working on.

The idea behind a pull/merge request is so common that github.com and gitlab.msu.edu both have the commands built right into the web interface to make the process as easy as possible.

The following video will walk you though a basic pull/merge request when you have write permissions on a repository. This is common for small groups but less common on big opens ource software projects. Most of the time developers do not have write permissions on the master branch (see next video for this, more common, case).

Review of commands used in video:

pwd
ls
git status
git branch BRANCHNAME
git checkout BRANCHNAME
clear
vi FILENAME
cat FILENAME
git commit -m "DESCRIPTION"
git push origin BRANCHNAME


## Forking a repository¶

A more common case for working as a collaborator to a repository is to work from your own copy (also known as a fork), develop your changes on your branch and then use github or gitlab to take your committed branch and use it to issue a pull/merge request.

This video describes the process of forking a repository and issuing a pull request.

Review of commands used in video:

git clone URL
cd FOLDER
ls
git branch BRANCHNAME
git checkout BRANCHNAME
git status
vi FILENAME
git commit -m "DESCRIPTION"
git push orign BRANCHNAME


## Managing the Upstream (a.k.a. Brining in collaborators changes)¶

Review of commands used in video:

git clone URL
git branch BRANCHNAME
git checkout BRANCHNAME
cat > FILENAME