Very brief introduction to Git

For homework and projects in this class, you must use a Git repository on Bitbucket – this page gives some brief instructions on how to use a Git repository in this manner, since most online Git tutorials focus on much more advanced features than you’ll need here (e.g. branches, etc.).

All of these instructions assume that you have command-line access to use git – as such they should apply to OS X and Linux operating systems that have Git installed. There exist graphical front-end programs that can use Git to interact with a repository; while you are welcome to use those tools, you need to figure them out for yourself.

In these instructions, all instructions will use my name (Reynolds) and will assume that I put the local version of my Git repository in the folder ~/Math6321 on my machine (recall, ~ corresponds to my “home” folder).

Setting up Git on your machine

Before you can use Git, you need to have it installed on your computer. I have already installed Git on all of the shared Linux machines in the Math department, but if you want to use Git on your personal computer you need to install it yourself.

Once Git is installed, it is useful to set some basic configuration options to help streamline your interactions with Git. These configuration changes are performed through using the command git config. There are tons of possible Git configuration options that you can find online. The few that I recommend are as follows:

  • user name – to tell Git your name so that all commit messages specify that you are the one that made them:

    $ git config --global user.name "Daniel Reynolds"
    
  • email address – to set your email address (not really necessary for this class, but if you work with others on codes in the future):

    $ git config --global user.email reynolds@smu.edu
    
  • preferred file editor – if you have a preferred program to use for editing text files on your computer, you should tell Git about it. Otherwise, Git will default to using the vi editor (powerful, but has an incredibly steep learning curve). To set this to geany on Linux systems:

    $ git config --global core.editor geany
    

Setting up your Git repository on Bitbucket

Navigate to the Bitbucket site. If you do not already have an account, create one. Once logged in, select the link Repositories -> Create repository from the top of the page. On that page, enter the relevant information for your new Math6321 repository:

  • Owner: drreynolds (replace with your Bitbucket username)
  • Repository name: Math6321-Reynolds (replace Reynolds with your surname)
  • Access level: This is a private repository
  • Repository type: Git

Then click the Create repository button. On the page that pops up, click the link under Command line -> I'm starting from scratch. The instructions below follow those on this page.

On your local machine, navigate to the folder that will contain your Git repository, and create the new folder for your local Git repository:

$ cd ~
$ mkdir Math6321

Initialize the new Git repository from within that new folder:

$ cd Math6321
$ git init

Link your local Git repository with the one you created on Bitbucket:

$ git remote add origin git@bitbucket.org:drreynolds/math6321-reynolds.git

(obviously, your last argument will differ from mine, where you instead use the command listed on the Bitbucket webpage).

We can create a ‘first file’ with some information about our repository:

$ geany README

In this file, I put the following text:

Repository for codes associated with the class:

   Math 6321
   Numerical Solution of Ordinary Differential Equations
   SMU Mathematics
   Fall 2016

This repository is owned by Daniel Reynolds.

We then ‘add’ and ‘commit’ this file to our local repository with the commands:

$ git add README
$ git commit -m "Added a README file"

To upload this to Bitbucket, we ‘push’ these changesets from our local Git repository up to our repository on Bitbucket:

$ git push -u origin master

The final step in setting up your repository is to update the permissions so that I can read and edit the files in your repository (for grading).

Back on the Bitbucket webpage, click on the menu item Settings at the left of the page. Under Security, click on User and group access. In the text box under Users type drreynolds. In the pull-down box to the right select Write. Finally, click Add.

Pulling in changes

Before you begin editing any files, I recommend that you first ‘pull’ any changes from the repository on Bitbucket into the Git repository on your local machine. Typically, your local Git repository will already contain everything from Bitbucket; however there are a few cases where Bitbucket could contain newer items than you have:

  • I have graded a previous assignment and pushed the grading files to Bitbucket.
  • You have edited files on a different computer and pushed them to Bitbucket.
  • You have come to my office for help and I have pushed updates to your repository to Bitbucket.

To download these changesets to your local Git repository, from within the local Git repository on your computer, you issue the ‘pull’ command:

$ cd ~/Math6321
$ git pull

Adding and committing files

From within the folder containing the Git repository on your local machine, you should create sub-folders to hold the codes for each homework and your project. For example, for homework 1, I would enter my Git repository folder and then create a new Linux/OS X folder like usual:

$ cd ~/Math6321
$ mkdir HW1

You should enter that new folder and create the files that you plan to use for your work, e.g.

$ cd HW1
$ geany prob2.cpp prob3.cpp Makefile &

At this point, I strongly recommend that you inquire about the status of the local Git repository with the command

$ git status

This will show a list of all changes to the local Git repository folder, including:

  • all files that were already part of the repository but that have been modified,
  • all files that are in the folder but that Git does not yet know about,
  • all files that have been ‘added’ to the repository but that still need to be committed.

I find this command to be incredibly useful, since it will also show any hidden files that you do not want to upload to Bitbucket (e.g. the OS X filesystem adds some terribly-annoying hidden folders .DS_Store to every folder).

Note

File types to add (or not) to a repository:

The idea behind a code repository is to save the source code for a software project. As a result, you should definitely add any files that are required to compile your project, including any extra files that your codes require (e.g. matrix.hpp and matrix.cpp). That said, many file types should not be added to a source code repository:

  • executables – these only work on one architecture (or machine), and are not portable to other machines or architectures
  • object files (e.g. foo.o) that are created during the compilation process – these are also specific to one architecture or machine
  • hidden system files or folders (e.g. .DS_Store in OS X)
  • backup files (e.g. foo.cpp~) that may be automatically created by your editor
  • output files that can be re-generated by running the code – this is debatable, but it’s generally considered bad practice to store/upload large output files

While you do not need to remove these from your local folder itself, you should not ‘add’ or ‘commit’ them to your Git repository, nor should you ‘push’ them to Bitbucket.

After finishing creating new files new files, or editing any pre-existing files, they must be ‘added’ to the local Git repository:

$ git add prob2.cpp prob3.cpp Makefile

You should then ‘commit’ these additions to your local repository, adding a useful commit message to explain what was added and/or modified:

$ git commit -m "Initial draft of my files for homework 1"

I recommend that you add/commit your files when you begin writing them, and as you complete each function and/or file that you add/commit them to record your progress. This has the added benefit of allowing you to revert back to a previously-saved state, in case you accidentally deleted or broke something in your work.

Merging

At this point, the Git repository on your local machine has new files and/or changes that have not yet been uploaded to Bitbucket – i.e. your repository is ‘ahead’ of the main Bitbucket repository.

Before you can upload any of your new work to Bitbucket, you must again ‘pull’ any changes from the repository on Bitbucket onto your local computer so that these can be merged. If you pulled recently, then it is likely that this step is unnecessary. However, if it has been some time since your last ‘pull’ then there could easily be changes that you need to download, especially if I have done any grading or if you’ve come to my office for help with your work.

Pull like before:

$ git pull

If anything has been added to the Bitbucket repository that is not yet on your local computer, it will be downloaded. If any changes were made to files that you have not changed, they will be automatically updated. If any changes were made to files that you have changed, Git will attempt to perform the merge automatically, but it may prompt you for assistance.

Once the merge is complete, you will need to ‘commit’ the merge. Depending on your Git configuration, your editor may pop up with a window requesting a ‘commit message’ for the merge – the default text is typically sufficient, so you can just save the file and close the editor. If this does not occur, then you should commit at the command-line as usual:

$ git commit -m "Merged with changes from main Bitbucket repository"

Pushing to Bitbucket

Before ‘pushing’ your files, I always recommend that you again inquire about the status of your local repository:

$ git status

If you have modified files but not added/committed them, they will be shown. If you have new files in the folder that have not been added/committed, they will be shown. If everything is ready to go, you should see a message similar to:

On branch master
Your branch is ahead of 'origin/master' by 2 commits.
  (use "git push" to publish your local commits)
nothing to commit, working directory clean

At this point, I will often try to ‘pull’ one more time to ensure that my local repository is completely updated. If there’s nothing left to download, you should get a message similar to:

Already up-to-date.

At this point, you can ‘push’ your changes to Bitbucket:

$ git push

I’ll note that from this point on, all ‘push’ commands from within your local repository no longer require the extra -u origin master arguments, since you have already informed your local Git repository to consider Bitbucket as the origin/master.

You can verify that everything has been synched correctly in two ways. First, the command

$ git status

should display something similar to

On branch master
Your branch is up-to-date with 'origin/master'.
nothing to commit, working directory clean

Second, on the Bitbucket webpage for your repository you should see all of your recent ‘commit’ messages at the right of the window, and if you navigate to Source on the left you should be able to see all of your newly added/edited files.

Coming to office hours for coding help

I strongly recommend that if you plan to come to office hours with coding questions, you should add/committ/push all of your files to Bitbucket before you come to my office. That way I can download your files, we can modify them together, and I can then add/commit/push them back up to Bitbucket for you to retrieve.