GitHub Workflow

github-workflow.md

GitHub Workflow

1. Open a command/terminal window

A command/terminal window will be used to execute the Git commands below.

macOS

Launch the Terminal application:

Applications > Utilities > Terminal

Windows 10

Open a Command Prompt window:

Start menu > W > Windows System > Command Prompt

2. Install Git

Check if Git is already installed on your system. If so, the following commands should reveal the location of the Git executable on your system.

macOS

which git

Windows 10

where git

If Git is not already installed, follow the official instructions to install it: https://git-scm.com/book/en/Getting-Started-Installing-Git

For Windows, it is assumed that you are using 64-bit Git for Windows and the Git BASH shell.

3. Configure Git

There are many possible configuration options in Git, but at the very least, set the username and email address that will apply to all Git repositories within your own user account.

git config --global user.name "YourFirstName YourLastName"
git config --global user.email "your.username@yourdomain.tld"

NOTE: The --global option will configure settings globally for your account only - that is, these settings will apply to all repositories under your own account, not to the entire system. Other git config options are as follows:

• System-wide (all users): git config --system
  • Unix/Linux/macOS file: /etc/gitconfig
  • Windows 10 file: %PROGRAMFILES%\Git\mingw64\etc\gitconfig
  • To check it: git config --system --list --show-origin
• User-wide (all repositories for only the current user): git config --global
  • Unix/Linux/macOS file: ~/.gitconfig
  • Windows 10 file: %HOMEPATH%\.gitconfig
  • To check it: git config --global --list --show-origin
• Local (for only the current repository): git config --local
  • File (within repository): .git/config
  • To check it: git config --local --list --show-origin

4. Go to the working directory where the GitHub repository will be cloned

macOS

cd /path/to/working/directory

Windows 10

cd /c/path/to/working/directory

5. Clone the GitHub repository.

https://help.github.com/articles/fetching-a-remote/

git clone https://github.com/USERNAME/REPOSITORY.git

Then go into the cloned repository.

cd REPOSITORY

6. Configure upstream remote repository (for forks)

https://help.github.com/articles/configuring-a-remote-for-a-fork/

If you have forked from an upstream repository, and want to keep your fork up-to-date with the upstream repository, then configure your local repository with the original upstream remote repository (called "upstream" by convention).

git remote add upstream https://github.com/ORIGINAL_OWNER/ORIGINAL_REPOSITORY.git

To check it:

git remote --verbose

7. Pull and apply updates from upstream repository (for forks)

https://help.github.com/articles/syncing-a-fork/

First make sure you are working on the local "master" branch:

git checkout master

Now pull updates from the forked upstream repository.

git pull upstream master

Finally, push the updates

git push origin master

8. Create a topic branch to work on (optional)

In the GitHub web UI, select the branch to branch from (typically "master"), then enter a new branch name to create the new branch.

TIP: Begin branch names with consistent tokens (such as "bugfix_") to help keep them organized.

git pull origin

Switch to the new branch to begin working on it.

git checkout new-branch-name

TODO:

• make changes, stage and commit them, and push them
• merge updates from base (master) or upstream into the branch
• merge updates from the branch into the base (master)
• but not for future pull requests; instead rebase?