Setting up Git for the command line

This guide is intended for windows, but may be applicable in part to other operating systems. Lines beginning with > are commands, and the > should be omitted when running them.

Initial Setup

Before you can submit pull requests (PRs), some setup is required. This should only need to be done once, or partially if you change computers or delete your repository folder.

Install Git

First, go to https://git-scm.com/download and download the setup file for your operating system.

Run the installer (requires admin elevation), and configure the following options (leaving others as defaults):

• Set the default editor to something other than vim - VSC or Notepad++ are good options if you have them installed, otherwise use Nano.
• For 'Adjusting your PATH environment', set it to the middle option - 'Git from the command line'.
• For 'Configuring the line ending conversions', set to either of the top two options.

Configure Git

Open the command prompt (Win+X -> PowerShell on Windows 10), and enter the following commands, adjusting as appropriate.

> git config --global user.name "UristMcContributor"
> git config --global user.email urist@example.com

Note: These values will be visible in the public commit log. Try to use an email address that's associated with your GitHub account so that the web UI can properly attribute commits.

Fork the Repo

If you haven't already, fork the BS12 repo by clicking the 'Fork' button in the top right - this will create a copy of the repo on your account that you can modify. Don't change the repo name if prompted.

Clone your fork

In a command prompt, cd into the directory where you want your repository to be saved, then run:

> git clone https://github.com/YOURUSERNAME/Baystation12.git

This will make a local copy of your fork on your computer that you can edit.

Setup Remotes

cd into the folder that the above step created, and run the following:

> git remote add upstream https://github.com/Baystation12/Baystation12.git
> git fetch --all

This will allow you to fetch commits from bay's repo to update your branches.

Pull Request Workflow

The rest of this guide is focussed on the general pull request workflow that you'll need to submit pull requests to the repository.

Create a Branch

In your repository folder, run:

> git fetch --all
> git checkout -b YOURBRANCHNAME upstream/dev

This will create a new branch named YOURBRANCHNAME with all commits from the upstream bay repo.

Add Commits

You can stage files for commit using the git add subcommand. Git will stage every path after add, and you can stage multiple files at once. The asterisk (*) character can be used as a wildcard.

Examples:

• Stage one file: git add file1
• Stage multiple files: git add file1 file2 code/file3
• Stage a directory: git add code/foobars/*

Once all your changes are staged, run git commit -m "YOURMESSAGE" to commit them. A message must be supplied, and it should be under 60 characters if possible.

Pushing to a Remote

Once your commit(s) have been made, you then must push your changes to the remote (GitHub) in order to have them show in a PR.

If the branch is new and has not been pushed to GitHub yet, do: git push -u origin YOURBRANCHNAME

If the branch has already been pushed to GitHub in the past, just do: git push

Making a Pull Request

Once your changes are complete, you need to submit a pull request so that maintainers can review and merge your code.

The Trivial Way

When you push to your fork, git CLI should give you a link that will directly take you to the PR editor for your branch. Just fill in the title and PR body and you should be good to go.

The Easy Way

If you have just pushed your branch recently, making a PR is very easy. Go to https://github.com/Baystation12/Baystation12 and look for a button that says 'Compare & Pull Request'. Clicking this button should open the new PR page with the correct branches already selected for you. Fill in your title and PR body, and click 'Create pull request.'

The Less Easy Way

If you haven't pushed to your branch recently, you'll need to explicitly tell GitHub which branch you want to PR. Click the 'New pull request' button on the repository page, then click the 'compare across forks' hyperlink under the page title.

Change 'head repository' to your repository, then change the 'compare' drop-down beside it to your branch. Once this is done, the PR editor should open and you should be able to continue like with the easy way.