Git Guide

Getting Started

Access Tokens

In order to access iSchool repos on GitHub Education, you’ll need to create a personal access token, which will be used like a password. Follow the steps in the GitHub documentation to create your personal access token. Make sure you save your access token someplace where you'll be able to find it again; once you leave the GitHub page where the token was created, you won't be able to see it there again.

Note that when you're prompted for a password, like when calling git push, you actually need to enter your access token.

Installing Git

If you don’t already have Git on your computer, you’ll need to install it.

Git Commands Reference

git clone

Download a copy of a repository into a new directory.

git checkout [-b]

Switch to a different branch; specify the -b flag to create a new branch.

git add .

Place new files under version control.

git status

Show the current state of the working tree (i.e., the files that you’re working on).

Use the -s flag for a shortened view.

git commit [-am]

Record changes that you’ve made to the repository.

Use the -a flag to automatically include files that you’ve modified or deleted; you’ll still need to use “git add .” to include any new files that you’ve created.

Use the -m flag to include a commit message; best practice is to preface your commit message with the ticket ID for whatever task you’re working on.

git push

Update the remote repository (i.e., GitHub Classroom) with the changes that you’ve committed to your local repository.

git merge

Join two branches together.

git log

See a history of commits for your current branch.

Use “git log --graph --decorate --oneline” for a concise view.

git branch [-D]

See the name of the branch that you’re currently on.

Use the -D flag to delete the branch.

git pull

Retrieve the latest commits on a branch from a remote repository.

git fetch

Get the list of available branches from a remote repository; often needed before “git pull”

Commit Message Best Practices

Short example:

PROJ-123 Refactor function foobar() to reduce complexity

Longer example:

PROJ-123 Refactor function foobar() to reduce complexity

* Remove nested loops
* Add meaningful variable names
* Convert nested tertiary operators to 'if' statements

These are the general rules to keep in mind when writing a commit message:

1. Start each commit message with a ticket number, such as from Jira or Azure DevOps
   • This is really important! Branches disappear, but commit messages remain forever
   • Including the ticket number makes it a lot easier to figure out which task corresponds to that commit
   • In the example: "PROJ-123" would correspond to a ticket in Jira or Azure DevOps
2. Include a pithy subject line for each commit; add a longer body for larger commits
   • In the longer example: the subject line (the first line) is kept short, and then more details are added in the body
3. Use bullets (asterisks) for the body, when necessary, to clearly indicate all the work done in the commit
   • In the longer example: three bullets are used to itemize the work that was actually done to refactor the function
4. Separate subject from body with a blank line
   • In the longer example: see how there's nothing on the second line?
5. Limit the subject line to 80 characters and wrap the body at 80 characters
   • In the example: even with the ticket number, the total length of the subject line is 56 characters
6. Capitalize the subject line
   • In the example: the first letter is capitalized in "Refactor", "Remove", "Add", and "Convert"
7. Do not end the subject line with a period
   • In the example: witness no periods. If the lines in the body grow longer, then it's find to separate sentences with periods or other punctuation
8. Use the imperative mood in the subject line; i.e., write it as a present-tense command.
   • In the example: it's "Refactor function", not "Refactored function" or "Refactors function"
   • When you're reading through commits and determining what will happen if you merge the commit into your branch, you should be able to prepend each commit message with, "If I merge this commit, it'll <commit message>". E.g., "If I merge this commit, it'll refactor function foobar() to reduce complexity"
9. Use the body to explain what and why, not how
   • E.g., don't say: "Call filter_var( $input, FILTER_SANITIZE_EMAIL )" Do say: "Sanitize email input to prevent CSS"

Most of these rules are taken from Chris Beams. See his blog post for a more thorough explanation of these rules.