# Working with Git Repositories in Kit

Some intermediate or advanced courses may have you submit your work to
a Git repository in Kit, and may also provide starter files or other
resources in a git repository.

Although Git is a sophisticated version control system, you will only need
a small subset of `git` commands to download and submit projects in Kit.
If you've never used Git before, though, you will need to go through a few
steps to configure Git, set up a public/private SSH key pair, and share
your public key with Kit.  You can find links to the relevant instructions
below.  (You can find similar instructions online, since you would go
through the same steps to get started with the widely-used Git server,
GitHub.)

Once you have defined your name and email address within Git and shared
your public key with Kit, you are ready to download and work with a
repository for an assignment.

## Setting up Git (one-time-per-machine)

- [Getting Started with Git -- Basic
Configuration](https://www.cs.kzoo.edu/CSShared/HelpFiles/GettingStartedWithBashOrGit/gitConfigure.md)
    ([plain text format](https://www.cs.kzoo.edu/CSShared/HelpFiles/GettingStartedWithBashOrGit/gitConfigure.txt))
- [Setting Up SSH Keys on Kit](https://www.cs.kzoo.edu/CSShared/HelpFiles/GettingStartedWithBashOrGit/gitSSHkeys.md)
    ([plain text format](https://www.cs.kzoo.edu/CSShared/HelpFiles/GettingStartedWithBashOrGit/gitSSHkeys.txt))

## Getting a Git repository for an Assignment

If an assignment has a Git repository associated with it, you will see a
"Start" button rather than a "View & Submit" button under the Submit
column.  When you click on the "Start" button, you will be prompted to
create a "cloned repository" (your own copy of the project) with a second
"Start" button.

The resulting Submission page will contain a line that looks like

    Repository URL: git@kit.cs.kzoo.edu:r190

but with a different unique repository number (not `r190`).

At a Unix/Linux/bash command line, go to the directory where you want to
download the repository.  Copy the repository URL from the Submission page
(e.g., <code>git@kit.cs.kzoo.edu:r190</code>) and paste into the following
command on the command line:

    git clone _full_repository_name_
       (e.g.,  git clone git@kit.cs.kzoo.edu:r190)

When the clone is done, you will have a new directory called `r190` (or
whatever the repository name was), which may contain instructions or
starter code.  You can rename the directory to something more meaningful,
like `ProgProj1`, if you want.

## The Basic Edit-Test-Save Cycle

Move into the directory containing the new repository (e.g., `cd r190` or
`cd ProgProj1`).  This is where you will create new files or modify
existing ones.  A good software development practice is to start by writing
the smallest amount of code that you can test, test it, then continue by
adding small, incremental changes and testing all along the way. (This is
sometimes known as _Agile Development_; _Iterative, Incremental
Development_; or "always have working code.")  In fact, depending on the
starting code provided to you, you may be able to run a simple test before
you make any changes at all.

Every time you make a change that you can test, you should save that
intermediate version of your project to Git locally, on your own machine.
This is basically a two-step process: (1) add the created or modified files
to the "staging area", and then (2) commit everything in the "staging area"
to Git.

1. **Staging:** A commit will only include the changed files that
   you have said you want to be part of the commit  (i.e., that you have
   "staged").  You can also have other changes that you aren't ready
   to commit; if you haven't "staged" them, they just get ignored.
   To add a file (or files) that you have created or modified to the
   "staging area", use `git add`:
        git add myFile.c
        git add *.c *.h
   If you make further changes to the program, you need to do a `git add`
   again, because you want to add those changes to the staging area also.
   A very handy command for seeing what files have been staged
   (marked for future commital) and what files have been changed but not
   staged is 
        git status

2. **Committing:** When you have a working version of your program (even
   if it is just a working intermediate step), commit your changes with the
   `git commit` command, specifying a short (less than 50 characters)
   message that describes the change.  Some examples:
        git commit -m "Add function calls to test binToDec"
        git commit -m "Improve Help Files"
        git commit -m "Update web site for new quarter"

If you want to see the results of what you have done, you can do a `git
status` again, or you can ask Git for a history of your commits.  There are
a number of ways to do this; here are just two.  The first is simpler but
more verbose; the second produces shorter summary information, formatted
nicely.

    git log --stat -5  (-5 means last 5 commits, --stat = statistics)
    git log -10 --pretty=format:"%h - %an, %ar : %s" (pretty print last 10 commits)

This is just the tip of the iceberg in terms of Git commands.  There are
commands to remove files from the repository, remove files from the staging
area but not from the repository, change the names of files, allow you to
see the changes between the current version of a file and a previous
version, see what commits have been made in the past, and more.  For more
information, see the [Getting Started with
Git](https://www.cs.kzoo.edu/CSShared/HelpFiles/GettingStartedWithBashOrGit/gitGettingStarted.md) document, which
has a fuller set of basic commands and links to external, authoritative
resources.

## Submitting a Git repository to Kit

You can update your Git repository on Kit as often as you like (this serves
as a useful backup system).

    git push

You can see that the push has been successful if you go to the View/Submit
page for the assignment and look at the Repository Log.  The Log will show
you all commits that have been pushed to Kit, including instructor commits
of the initial version of the repository and any you have pushed since
then.

## Sample, simple scenario

1. Edit your program to add a new feature.  Test it.

2. Stage and Commit:
            git status         Will show you what needs to be staged
            git add myFile.c   Stages new C source file
            git add header.h   Stages modified C header file
              [might also need to do a "git rm" or two]
            git status         Make sure everything you want has been staged
            git commit -m "Short message saying added new feature"

3. Push to Kit
            git push

4. Loop back to #1: Edit your program to add a new feature and test it.

## Final submission to Kit

When you are done, go to the Submission page in Kit and click on the "Turn
In" button.  Once you do this, though, you will only have read-only access
to your Kit repository.