git

This page covers how I use Git and GitHub to edit and collaborate on code. It might not be best practice, it's just what works best for me so far.

Git is a tool used to store open-source code (such as test suites) and allow people to collaborate on it.

Broadly what it helps you do is to:

• create a copy (branch) of existing code
• make changes to it
• commit (save) the changes
• push them back to GitHub
• get the changes reviewed by raising a "pull request"
• merge the changes into the main code branch

Some terminology:

• Git is the core version control system that you access through your command prompt.
• GitHub is the website which shows everyone's code, and manages pull requests.
• GitHub Desktop is the (optional) desktop app that makes it easier to work with your project without using the command prompt.

Setup

If you're new to GitHub then the GitHub Hello World tutorial is worth doing.

You will need:

• An Mac or PC with enough rights to install things on it
• On a Mac, it's worth installing Homebrew first, to make it easier to install lots of other things.
• A GitHub account
• Access to push to your repository - contact an existing member of the team.
• A command line tool such as Terminal on Mac (built in) or git bash on Windows
• A text editor such as Visual Studio Code
• A means to upload to GitHub. You can use the command line directly, or an app such as GitHub Desktop.

Once you have these, then:

• Install and set up Git on your machine. Alternatively, there are some useful Mac-specific setup instructions from Alan Cruikshanks.
• Certain actions, such as pushing code to GitHub, will prompt you to log in. If this is your first time doing so, you'll need to set up a personal access token or use an alternative method of logging in. When prompted for a password, use the token you have generated instead.
• Navigate to the root folder in your command line / terminal with cd ~
• Create and navigate to a projects folder: mkdir projects and cd projects
• Copy the latest code from the repository you're working with. For example, git clone https://github.com/andrewhick/qa-test.git
• Navigate to the repository folder: cd qa-test

You should now be ready to start work on a repository.

Some principles

• Work in the open by default.
• But - do NOT publish usernames, user data, keys and passwords on GitHub.
• Everyone makes mistakes, so always get a colleague to review your pull requests.

Updating your code through GitHub

These are the most common steps for updating a test repository, using the command prompt. The examples assume that you're working on a branch called add-accessibility-page in the qa-test repository, which is in your local projects folder.

Make sure you have the latest code

Start the command prompt, navigate to your project folder and pull the code from the repository:

cd projects/qa-test
git pull

This doesn't overwrite any code you've already written on your machine. If you don't do this then you're much more likely to have conflicts to deal with later.

Set up a new branch

Think of a descriptive name for the branch based on what you're planning to work on, for example, "add-accessibility-page".

The easiest way to create a branch is:

git checkout -b add-accessibility-page

When you next commit and push upstream, this will create a copy of that branch on GitHub.

If you've already created the branch via GitHub, then you'll need to ensure that the changes you make on your machine stay in sync with the changes on the same branch in Git:

git checkout -b add-accessibility-page
git pull
git branch --set-upstream-to=origin/add-accessibility-page

The git pull in the middle is useful because it prompts you to do the "set upstream" step afterwards.

Write your code

Write your code, saving regularly to your local machine. When you've reached a natural break, then you can commit (save) the changes and push them to Git.

At regular intervals, it's useful to check the status of what's going to be committed. git status is always useful if you're lost.

A common mistake is to forget to add any new files to the commit. If you’ve created any files, add them. If you don't do this, the new files won't be committed.

The following steps add any new files, check the status, commit the changes with a message and then push the code to Git. You don't have to keep checking the status, but it's useful to see where you are the first few times:

git add -A
git status
git commit -m "Add a new accessibility page"
git push -u origin add-accessibility-page
git status

Some abbreviations:

• -A means "all files"
• -a means "all modified or deleted files"
• . means "any changed files"
• -u means "upstream" - this ensures that the new branch you've created gets copied to GitHub.

If you want to commit all modified files at once and skip the add step, you can add a flag like -a to the commit, for example git commit -am "Add a new accessibility page". However, this can make it easy for you to commit files that aren't part of your current work.

Create a pull request

A pull request (PR) is asking your colleagues if they're happy for you to pull your changes into the main branch of the repository. This must always be shippable, so it's your responsibility to ensure that the code works beforehand.

Before you raise a pull request, you therefore need to:

• Ensure that all of your tests pass.
• 'Lint' your code. This is like a spelling and grammar check that your code is good enough to go live with. How you do this depends on the framework you use. For Ruby-based frameworks we do this with Rubocop (bundle exec rubocop) which points out code issues and tells you how to fix them. You can also install inline linting tools in your text editor.
• Remove any "work in progress" tags as they can cause any Continuous Integration built into GitHub to fail.

If you've made any changes as a result, then commit and push them to your branch.

You can then:

• Navigate to the branch on GitHub
• Click "Compare and pull request"
• Resolve any conflicts that appear
• Add a brief comment explaining why you're making the changes
• Review any automated checks that GitHub carries out on the repository. If they fail, then check the logs and discuss with a colleague if unsure.
• Create the pull request
• Nominate a reviewer (it's polite to talk to them too!)

If your colleagues suggest changes, then you can make these, commit and push to the branch in the same way that you did before, double-checking that your tests still pass.

Merge your code

Once your colleagues are happy with the code and all automated checks pass, you can then squash and merge the code on the pull request page.

You should then take the opportunity to delete the branch you worked on.

To help prevent the code getting out of sync on your local machine, you should then also switch to main or master and pull the latest code:

git checkout main
git pull

You should then switch to a new branch when you start a new piece of work.

Fixing errors

It's very easy to make mistakes in Git, but they can usually be corrected. In general, committing little and often, and keeping your pull requests small are the safest ways to prevent things going wrong.

Reset a local file back to main

If there are edits in a local file and you want to quickly revert it to main, you can checkout the main version of that file:

git checkout main path/to/file

Exclude a file from a commit

Alternatively, if you want to keep the edits you've made from a file that you've added (via git add) but you want to exclude it from your current commit, use:

git reset HEAD -- path/to/file

This effectively reverses your add statement.

Amend the previous commit

To overwrite the previous commit without making further changes:

git commit --amend --no-edit

To overwrite the previous commit and change the message:

git commit --amend -m "This is the new commit message"

Force push

If you have pushed too much in one go and want to revert some changes, Git will not let you push the reverted changes automatically and will return an error such as "Updates were rejected because the tip of your current branch is behind its remote counterpart."

If this happens and you still want to revert the changes, you need to force push as follows:

git push --force -u origin your-branch-name
# or
git push -f -u origin your-branch-name

Remove commits from a pull request

If you have started from the wrong base, your pull request commit history may end up with incorrect commits from other work you have been doing. It is possible to remove commits from a pull request with:

git checkout my-pull-request-branch
git rebase -i HEAD~n # where n is the number of last commits you want to include in interactive rebase.
# This should open your code editor. There, replace "pick" with "drop" for commits you want to discard. (There's more context on this in the link).
# Save and exit.
git push --force-with-lease

Hard reset

Sometimes, Git and your computer can get out of sync. If you're certain that the "remote" (online) version of the code is correct (make a backup if unsure), then use the following:

git fetch origin
git reset --hard origin/main

Ensure you can run Code from the shell (Terminal)

When carrying out certain commands, like rebase, you may get an error as follows:

hint: Waiting for your editor to close the file... code --wait --disable-extensions: code: command not found
error: There was a problem with the editor 'code --wait --disable-extensions'.

To fix this for the Code editor, follow the "launching from the command line" steps.

Masking passwords

Never publish passwords or any other sensitive data to GitHub. Even if you remove them later, GitHub stores all old versions of code, so they're still accessible.

As automated tests often rely on login details however, you need a way to send passwords to your tests. How you do this depends on your framework, but there are two main methods:

Method 1: Environment variables

Your framework may allow you to pass in passwords as environment variables to your test. On a Mac, this means updating your .bash_profile file to include the variables, and calling them from your tests.

Method 2: Exclude the config file from Git

You can put passwords in a config file, then set a .gitignore file in your repository to exclude your config files from commits.

Whichever method you use, speak to a colleague who has done something similar, who can advise on the best way to do this.

Other things you can do

Stash your work

If you need to switch between branches, you may be prompted to stash your work on that branch so that you don't lose your work. Use git stash to store your changes, and git stash pop to get them back again.

Stage only some of your changes

If you have made some changes but wish to split them across multiple commits, then you can select each change and decide whether to stage it individually for your next commit. Do this by:

git add --patch
# or
git add -p

You will then be prompted whether to stage each change or not as follows:

(1/1) Stage this hunk [y,n,q,a,d,e,?]? ?
y - stage this hunk
n - do not stage this hunk
q - quit; do not stage this hunk or any of the remaining ones
a - stage this hunk and all later hunks in the file
d - do not stage this hunk or any of the later hunks in the file
e - manually edit the current hunk
? - print help

Co-author a commit

To add an author to a commit, add their publicly-shareable email address to the commit message separated by two empty lines like this:

git commit -am "Your commit message


Co-authored-by: co.author@example.com>"

More information on co-authoring

View recent commit log

Type git log -x where x is the number of previous commits you want to view

Set up a GitHub Pages site

Go to GitHub Pages.

Things I haven't got to work yet

Remove files that were incorrectly pushed

If you've accidentally changed a file, and committed and pushed the changes, you can remove that file from the push as follows:

git checkout HEAD^ -- /path/to/file # allows you to revert the changes from a particular file
git commit --amend --no-edit # amends the previous commit (as above)
git push -f -u origin your-branch-name # force pushes the change (as above)