03 Git Basics

This is a short introduction to one of the most essential tools in software development: a version control system and in particular the Git tool.¹

A version control system (VCS) manages files and tracks changes to those files. It stores the complete history and allows you to recover files at any stage of the history (think "undo" to the beginning). Any serious software project uses version control but its uses go beyond software, e.g., documents and data can also be version controlled.

A set of changes is called a commit. It typically contains changes to multiple files. It also contains a timestamp, information about the user who made the changes, and a commit message that explains the changes. The history consists of all the commits. The VCS stores the history in a storage area called a repository.

Modern distributed VCS such as Git or mercurial make it easy for multiple developers to work on the same project. They have support for merging changes from different people into a single new file, and for resolving conflicts, i.e., the case when the same part of a file was changed (the changes "collided"). Online platforms such as GitHub or Bitbucket provide free repositories in the cloud (but you don't need these platforms to use a VCS!).

We will use Git. For the class you should get into the habit to version-control your work: in class notes, home works, and projects. You will use GitHub to submit code that you develop as part of your assignments and projects.

1. Tutorial
2. Set up your own GitHub repositories
3. Class resources on GitHub
4. Additional resources

Tutorial

Let's use git to manage what we have done so far.

If you want to read more about Git, have a look at the free Pro Git Book by Scott Chacon and Ben Straub and see the other resources.

Configuring Git

The first time you use git you need to tell it who you are: this information will be the user information in the commit history.

Personalization

Set your name and email.

Use a name and email address that can appear in the clear in the world because you will also use it to sign up and access the GitHub web site; if you are concerned about privacy, please review GitHub’s instructions for keeping your email address private. During this class we will use GitHub all the time:

• Homework will be submitted to private git repositories (only visible to you and the instructors).
• Projects will be submitted to private repositories only visible to you, your team, and the instructors.
• The final project will be submitted to a public repository, visible to everyone in the world.

Set the name and email associated with your commits (Use your own name and email address!) (and how to color output):

git config --global user.name "Darth Vader"
git config --global user.email "dvader@empire.gov"
git config --global color.ui "auto"

There are subtle differences between how Windows and Linux/macOS treat line endings, which matters for programming. Without going into details, please set the following

On Windows

git config --global core.autocrlf true

On macOS or Linux

git config --global core.autocrlf input

You can see a list of all your configuration settings with git config --list.

Git Editor

You also tell what editor to use to write commit messages ²; here we configure atom to be used with git.

Windows

# choose atom as your editor: Windows
git config --global core.editor "C:/Users/USERNAME/AppData/Local/atom/bin/atom.cmd --wait"

where USERNAME should be your username. Double check that the path /c/Users/USERNAME/AppData/Local/atom/bin/atom.cmd really points to the atom command. (You can try the command which atom, which might show you the correct path on your computer.) Otherwise, add the correct path. Ask for help if necessary.

macOS and Linux

# choose atom as your editor: Linux and Mac
git config --global core.editor "atom --wait"

git basic command syntax

Git commands always follow the pattern

git <verb> [options] [arguments ...]

In particular, --help is always an option. Also try git help and git help tutorial.

Creating a repository

You alread should have a PHY494 directory in your home directory with a layout like the following (where 01_shell might contain other folders and documents):

~/PHY494/
        01_shell/
        02_python/
             hello.py
             motion.py

Turn the PHY494 directory into repository with the git init command:

cd ~/PHY494
git init

That's it. Although, not much happened yet… except, check with

ls -la

A new hidden directory ~/PHY494/.git/ appeared. This is your actual repository (or database) where Git stores all its information. Do not change anything in this directory (unless you really know what you are doing) and do not delete the .git directory. If you delete it, your repository is irrevocably gone (and there is no undo for that!).

Now try the (possibly) most-used git command:

git status

The three states of Git

For Git, a file can reside in one of three states

• Modified means that you have changed the file but have not committed it to your database yet; the file is in the working directory.
• Staged means that you have marked a modified file in its current version to go into your next commit snapshot; it lives in the staging area ³.
• Committed means that the data is safely stored in your local database (the git repository in the .git directory).

The basic Git workflow:

1. modify files in working directory
2. selectively stage changes that you want to include in your next commit (adds only those files to the staging area)
3. commit your changes (takes files from the staging area and stores them permanently in your Git repository)

Adding files

Prepare the modified files to be committed to the repository: git add adds files and directories to the staging area:

git add 02_python
git status

Add more files and directories:

git add 01_shell
git status

(Use git reset FILENAME to unstage any files that you might have added accidentally. For instance, do not checking backup files created by your editor.)

The files are not committed yet. You can do more work, add more files and directories…

Committing

Check-in (or commit) your changes to your git repository:

git commit

• When your editor pops up, enter a commit message: Convention:
  • first line (<60 char): one line summary
  • second line: blank
  • third and following lines: more details The first line is mandatory (you cannot have a commit without a message), the rest is optional. The commit message should succinctly summarize the changes in the commit.

  As an example, the following would make a good message:

  initial commit of PHY494 class work
    
  * lesson 01 on shell
  * lesson 02 on python
  

• After you wrote and saved the message ("save" in atom, ^O in nano; i to write and ESC :wq to save and exit vim) and exited ("quit" in atom, ^X in nano), your changes will be committed to the repository.
• You can also supply the message as an argument: git commit -m "one line summary of changes".
• Check the status with git status…

For a new commit, add files and commit again.

History

Git stores complete snapshots of your working tree in the repository: each version (or commit) can be used to recreate an exact state of all your files:

Read the history with

git log

Removing and renaming files

Removing files and directories via git allows you to get them back later.

git rm FILENAME
git rm -r DIRECTORY

Renaming is the same as removing the old file and adding the new one but there is also a simple command

git mv OLD NEW

The git rm and git mv commands are similar to the git add command in that they stage these changes; you still have to commit them.

Working with remote repositories

Initialize a local repository from a remote source:

git clone URL

Clone the repository where code and data will be posted:

cd ~
git clone https://github.com/ASU-CompMethodsPhysics-PHY494/PHY494-resources.git
cd PHY494-resources

Note:

• The local name of your repository can be any name you like but it is customary (and less confusing) if you go with the default, which is the remote repository name without the ".git" suffix, i.e., PHY494-resources for us.

• For all other git commands you must be inside your local repository:

    cd ~/PHY494-resources
  

Update your local repository with any "upstream" changes:

git pull

Update the remote repository with you local changes (commits):

git push

(For "pushing" to work, you must be allowed to write to the remote repository; this will not work for PHY494-resources but we will use it below for your own GitHub repositories).

Contributing to Open Source on GitHub

GitHub enables you to easily contribute to other projects. This includes

• filing bug reports or feature requests (raising issues); for instance, if you do not agree with some of the Star Wars data from the previous lessons, raise an issue in the issue tracker for the PHY494-auxilliary repository.
• proposing to add your own code and changes through pull requests (but this is too advanced for a our short introduction today — see the additional resources under More…).

Set up your own GitHub repositories

1. Go to https://github.com and create a new account. It is free.⁴ Remember your GitHub username and the password.
2. Create a new repository PHY494.
3. Note the repository URL https://github.com/USERNAME/PHY494.git

4. Add the remote repository to your local repository ~/PHY494 (replace USERNAME with your GitHub username):

    git remote add origin https://github.com/USERNAME/PHY494.git
   

   We named the remote "origin", which is a common choice for the main repository. You can have many different remotes, just give them different names. You can list them with

    git remote -v
   

5. push your local history to the remote repository:

    git push --set-upstream origin master
   

   You need to enter your username and password ⁵.

   You only need the --set-upstream origin master (or -u origin master) for the first time (it tells git which "branches" to associate with each other in local and remote) ⁶. All further push operations will then simply be

    git push
   

   Look at the web interface at https://github.com/USERNAME/PHY494 and see your changes appear.

For the rest of the semester, commit what you did during each class session to the ~/PHY494 repository on your laptop (and also push to your GitHub repository as a backup).

Note: Your GitHub repository is public. Do not commit homeworks there; you will receive a private repository for the duration of the class for this purpose.

Class resources on GitHub

Code, notebooks, and files are being made available on GitHub in the repository ASU-CompMethodsPhysics-PHY494/PHY494-resources. If you have not done so already:

cd ~
git clone https://github.com/ASU-CompMethodsPhysics-PHY494/PHY494-resources.git

Update when your instructor changed anything on the remote:

cd ~/PHY494-resources
git pull

Note that you should not be changing anything inside ~/PHY494-resources but instead copy whatever you want to change to your own work directory.

If you happen to have accidentally edited files inside ~/PHY494-resources you might run into merge conflicts when you run git pull the next time. If that happens, copy all files that you edited (use git status to see which ones are modified) to a safe directory and then reset with the command

cd ~/PHY494-resources
# Next command only if you ran into a merge conflict
# during a 'git pull'
git merge --abort

# undo ALL of YOUR changes
git reset --hard HEAD

WARNING: This will undo all your changes but will allow you to just run the next git pull command again without problems.)

More…

• For a longer introductory tutorial see the Software Carpentry lesson on Version Control with Git.
• Interactive in-browser lesson Try Git, takes 15 minutes.
• Blischak JD, Davenport ER, Wilson G (2016). A Quick Introduction to Version Control with Git and GitHub. PLoS Comput Biol 12(1): e1004668. doi:10.1371/journal.pcbi.1004668
• For in-depth discussion read the Pro Git book by Scott Chacon and Ben Straub.

Footnotes