Learning Git with GitHub Desktop

If you have a programming project that you are working on, chances are your workflow would be improved by adding version control. Version control makes it easier for you to back up your work, keep a history of changes you have made, work collaboratively, and share your code. Git has emerged as by far the most popular version control option, so that is what we will learn. We will be using GitHub Desktop as it makes it easy to get started.

Preparation

Your first repository

Adding a project

Let's add a project to version control. This tells git that we will want to track some of the files under this local directory.

1. Click on + -> Create
2. Choose name and path (root directory).
3. Name: Pirate, Path ~/Documents (you can let it be anything, but please remember the path).
4. Click Create Repository.

Creating files to track

Version control only works if you have files to track, so let's make some files.

# In a bash terminal
cd <path>/Pirate
nano pirate.py

# In pirate.py
import random
print "arr, matey"

# Save the file

Status

The status tells you what changes you've made that are not in git yet.

Look at the status by clicking on the tab that should say 1 Uncommitted Change. Notice that clicking on a file shows you the changes from that file.

Your first commit

When you commit, you are telling git to keep track of all of the changes you have made. You create a checkpoint that you can go back to at anytime, and view differences.

Commit changes:

1. Type a detailed commit message in the Summary text box "Initial load of pirate treasure." (You can add a longer description if you want).
2. Click Commit to master button.

History

This history let you see all the commits you have made over time. Let's check the history now.

Click on History at the top. It just has a single commit now, but soon it will be more populated.

The git process

What will typically happen is that you make a few small changes, and then commit as you go. Make sure you put a detailed commit message for each commit so that you know what you did when (and why). This makes it easy to figure out where a bug came from or what your thought process was.

We'll make some more changes:

# Delete a line
We are not using the random module. Delete it from the file.
Commit "Removed unnecessary random module"
Check History

#Change a line
Capitalize 'Arr, matey'
Commit "Correct capitalization"
Check History

# Add some lines
for i in range(100):
  print str(i) + " bottles of rum"
Commit "Walk paces 1-100"
Check History

Undoing a commit

Sometimes you make a commit and shortly afterwards realize something went wrong, you spelled something wrong, the code doesn't do exactly what you wanted, etc. We can undo our most recent commit.

Undo a commit:

1. Click undo at the bottom of the Uncommitted Changes tab.
2. Make a better commit message and commit again "Walk paces 0-99".

Adding a file

We can track more than one file at a time (otherwise version control would be pretty useless).

Add a file:

# Add a new text file 'treasure.txt'
  Rubies
  Diamonds
  Crown Jewels
  Parrot

# Update pirate.py to read file and print out data
with open('treasure.txt') as fh:
  for line in fh:
    print line

1. Separate this into two commits by first unchecking pirate.py (only treasure.txt should be checked) and commit with message "Adding my treasure".
2. Then check pirate.py and commit with message "Print out treasure contents".

Ignoring files

We can tell git that we don't want to track some files. This is useful for output, configuration files, files with sensitive data (like passwords), or compiled files .

# Have pirate.py write a file
with open('map.txt', 'w') as fh:
  for i in range(10):
    fh.write("Walk " + str(i) + " paces left.")
# Run our program
python pirate.py

Now we want to commit, but we don't want to commit map.txt (now or ever).

1. Right click map.txt and pick ignore.
2. Notice we have a new file to add. The .gitignore file is a special file that tells you what types of files to ignore.
3. Aside: When you start a new project it is nice to search for something like 'python git ignore' in google and copy the resulting file into your own file.
4. Commit changes with message "Create a simple treasure map".
5. Look at .gitignore file it created.

Creating a remote repository

Right now all your files are on your computer, if you want to send them to the cloud so that you can share your code and have another backup of all your changes you create a remote. GitHub Desktop publishes your code to GitHub (though you can configure a different remote if you want).

1. Click on the Publish button in the upper right.
2. Write a description for your repo and then click Publish repository.
3. Go to GitHub and check out your new repo.

Adding a Readme

Once you have a repo publicly you should add a readme to help people who find your project understand what it is for and begin using it.

1. Create a new file README.md.
2. Write something that helps users understand how to use your repository. GitHub uses markdown to display formatting. Markdown Cheatsheet.
3. Commit your new file with message"Added readme".

Pushing changes to remote

You have committed your changes locally, but they are not on the remote repository (GitHub) yet. To get you changes to GitHub, you need to push your changes.

1. Click the sync button to push your changes to your remote repo.
2. Check GitHub see how it displays your readme to visitors.

Pulling changes from remote

You can make changes directly to the remote repo, or someone else can make their own changes and push them to remote. You will need to pull those changes back to your local repo.

1. First make sure you have no uncommitted changes locally.
2. Make a change to README.md on GitHub by clicking on README.md and then clicking on the edit (pencil) button.
3. Aside: It is fine to make small changes to readmes and text files directly on GitHub, but changes to code should be done in an environment where you can test your changes.
4. Commit changes by clicking the green commit button on GitHub.
5. Now click the sync button in GitHub Desktop to bring those changes back to your local repo.
6. Look at the History

Resetting a commit

If you have ever accidently created a commit and can't undo, you can revert your commit.

Add a bash command to your pirate.by file 
echo "Polly wants a cracker"

1. Commit your changes "parrot food" and sync with GitHub.
2. In History, click on the offending commit.
3. Click on the settings icon and select Revert this Commit.
4. To make sure you changes get to the remote repo, click on the sync button.

Branching

Branching allows you to make changes to your code while maintaining a stable core. A good model to follow is to make a branch for every new feature or bug fix you want to make and then to merge it back into master when you are done.

1. Click the +branch icon button.
2. Put 'gold' as the name and click the Create Branch button.
3. You have just created a copy of all your code, but changes here won't affect the code in master (until we merge it, next section).
4. To switch between branches use the dropdown next to the branch button.
5. Modify treasure.txt and add the following treasures:

Gold doubloons
Goldfish
Gold nuggets

6. Commit your changes with message "Added gold things to my treasures".
7. Switch to master branch (use the dropdown menu).
8. Look at treasure.txt and notice it doesn't have the gold things in it.

Merging

Once you have finished what you were working on in your branch, you can merge your code back into master.

1. Make sure you are on branch master.
2. Click on Compare and select gold.
3. Click Update from gold.
4. Look at treasure.txt. Notice it has all the gold treasures.
5. To get back to the normal view click View Branch

Merge conflicts

Sometimes someone git cannot figure out how to merge a file because the same line has been changed in both branches. This is called a merge conflict and you will have to tell git which lines you want to keep.

We are going to create a merge conflict by changing the same line in both branches. Git will require you to pick what you want to keep.

1. In branch master.
2. Change the line 'Goldfish' in treasure.txt to 'Golden retriever'.
3. Commit this file with message "Dogs > fish".
4. Switch to branch gold.
5. Change the line 'Goldfish' in treasure.txt to 'Golden marmoset'.
6. Commit this file with message "Monkeys are better for pirates".
7. Switch back to master.
8. Click Compare and select gold.
9. Click Update from gold.
10. Uh-oh! there are conflicts (as expected).
11. Choose Open with External Editor button.
12. Delete all lines besides the ones you want to keep.
13. Save the file.
14. Commit the changes in branch master.

Other ways to get repositories

Cloning

You can download someone else's git repo if they have made it public. This is called cloning. Be aware that you will only be able to make changes locally to a cloned repo unless the owner gives you permission. If you want to be able to push changes, you will learn that next section with forking.

Your clone list will be prepopulated with your own repos and those from organizations you belong to. To get one from somewhere else on GitHub:

1. Find an interesting repo at github.com's explore section.
2. Click on the green Clone or Download button.
3. Select Open in Desktop.

Forking

You can also make a copy of a repo to your own remote section; this is called forking a repository. Only do this if you plan to make changes to the code and push your changes remotely.

1. On GitHub click the fork link.
2. Now you can clone the fork from your location onto your desktop.

Adding an existing folder/repo

If you have a project that you have already started and want to add version control, or you have cloned a repo through other means besides GitHub Desktop you can add it.

1. Click the + -> Add and select the repo or folder you want to add.
2. Make your first commit and that's it!

Command line git

We have been using a GUI for performing all of our git actions, but you can do everything from the command line too. Using git from the command line give you access to more commands and options than are available with the desktop version, but with great power comes great complexity.

If you would like to learn command line git I recommend starting with Try Git.