Git And GitHub Reference And Quick Start Guide

When I started learning to code Subversion or ‘SVN’ was all the rage, and that’s what I went with. Time passed and the Git tsunami seems to have all but wiped out the competition. While I’ve stuck with SVN because it’s always worked and has never given me a reason to change, I figure I should do a few projects using Git and GitHub to familiarise myself with them and to see what they’re about.

To that end, the below is a quick start or reference guide for the most basic features of Git and GitHub.

Initial setup

Once git is installed we’ll need to configure our default identity which will be added to any code we commit.

git config --global user.email "you@yourdomain.com"
git config --global user.name "Your Name"

Creating a local repository

This will create a repository on the local machine. If we specify a project name, a folder with that name will be created, if we omit it, the current folder will the repository root.

git init <project_name>

Checking the status of a repository

At any time we can check the status of a git enabled folder

git status

Adding files to source control

Now that we have a repo, when we create some files we need to tell git “Hey, you need to look after these files”.

git add <filename>

Committing files and changes

Once we’ve made changes to a file we will want to commit those changes, or to tell git “Hey, I’ve changed a bunch of stuff, make a record of it”.

git commit -m "Commit Message -  a summary of changes"

Clarification on git add vs git commit

One thing I didn’t immediately grasp with git was the need to always add files before a commit, even if the files had been previously added to the repository. I was incorrectly under the assumption that once a file was added, like SVN, that was it, from there it was all commits.

Git works a little differently, files need to be added via git add both when they’re first created and are being added to the repository, and when a change to the file has been made that we wish to commit.

In short, git add adds files to the git index, which is staging area for files which are to be committed.

There is however a shortcut that we can use to add all changed files that have previously been added to the repository to the staging area and to commit them, with one command.

git commit -am <Commit Message>

Setting Git to ignore files or folders

Sometimes we have configuration files we want inside the repository folder for convenience, but we don’t want them added to source control, and certanly not uploaded to GitHub. Git makes this easy with .gitignore files. Simply create a file with that name in the repository and and newline separated paths that should be ignored.

config/
**/.terraform/*
*.tfstate
*.tfstate.*

GitHub Integration

Now that we have some local code, we want to sync it up to GitHub, either for collaboration or just to have an offsite copy.

Firstly we need to create a new repository on GitHub. Once created, GitHub will provide us instructions for pushing an existing local repository.

git remote add origin https://github.com/<git_username>/<repository_name>.git
git push -u origin master

Future updates we wish to push to GitHub are a bit similar

git push

Saving GitHub Credentials

By default the git won’t cache credentials, so each time we interact with GitHub we’ll be prompted to authenticate. This may be ok (albeit annoying) if you’re using a password, but once 2FA is enabled the git command line uses a 40 character access token as the password - not something I want to be looking for and pasting in every time I commit. We can enable credential caching on the local machine with the following command.

git config --global credential.helper wincred

This uses the Windows Credential manager to temporarily cache our authentication details. If the Credential Manager service (VaultSvc) is restarted, we will once again need to re-auth.

Working with multiple machines

Once our code is in GitHub we can clone it to another machine to continue working. The clone address will be available on GitHub under the repository.

git clone https://github.com/<git_username>/<repository_name>.git

This will create a folder with the repo name that contains our code. When we’re done making changes we can run the usual add, commit, and push (no need to specify the full address) to send our changes back to GitHub.

That’s it for now, while these are the utter basics it’s all I need on most days.

Removing a file from git

If we wish to remove a file from git, we have two options. If we only want to delete it from git, but leave a copy on the filesystem, use the command below.

git rm --cached byebye.txt
git commit -m "removed byebye.txt"

Otherwise, if we want to remove a file from both git and the local filesystem:

git rm byebye.txt
git commit -m "deleted byebye.txt"

Permanently removing a file from git and all history

To remove all historical and current commits of a file we need to use the following commands - thanks to this Stackoverflow post. The file path, in this example src/secretfile.txt, needs to be the relative path to the file from the root of the repository.

git filter-branch --force --index-filter 'git rm --cached --ignore-unmatch src/secretfile.txt' --prune-empty --tag-name-filter cat -- --all
git push --all --force

Branching

Branching allows us to create a snapshot of the current state of our code, do some work on it, then merge it back into the master branch.

View branches

The current branch will have an asterisk next to it.

git branch

Create a new branch

The following will create a branch from branch we’re currently in.

git branch <branch_name>

However, if we wish to be more explicit, we can specify the branch we want to create from, and we can immediately enter the newly created branch.

git checkout -b <new_branch_name> <original_branch>

Switching to a branch

Similar to the above command, we can switch to an existing branch as follows.

git checkout <branch_name>

Pushing a branch to GitHub

Once again we need to specify our upstream provider if we want to sync the new branch to GitHub.

git push --set-upstream origin <branch_name>

Further pushes can be carried with only git push as before.

Merging a branch into to master

Once we’re done making our changes, we’ll typically want to merge them back into the master branch. First we need to switch (checkout) to the branch we want to merge into, then we can perform the merge.

git checkout master
git merge --no-ff <branch_name>
git push

Deleting a branch

Finally, once we’ve merged out work into master, we can delete the branch - both locally and from GitHub.

git branch -d <branch_name>
git push -d origin <branch_name>