Table of Contents

Git is the version control tool used for this project. As not everyone will be familiar with it, this Wiki page features some handy beginner tips; there is loads of further information available all over the Web.

Terminology

Term	Definition
Working/local copy	The copy of the repo. that you have on your local machine
Remote/origin copy	The copy of the repo. on GitHub
Branch	A copy of the codebase used for development
`main`	The primary branch of the codebase - code cannot be committed directly
Pull request	A request to merge the code in a given branch with (usually) `main`
Checking out	Switching your local copy to a given branch
Staging	A modified file is staged before committing

Getting Started

Install Git (obviously)
Clone the repo. (git clone git@github.com:markcheret/footnotes.git)
View the available branches (git branch)
Set your user details:
- git config --global user.name "John Doe" and git config --global user.email johndoe@example.com
- if you want to use a local username/email that is different to your global one, drop the --global option
TODO: Add SVN details to your Git config

Workflow

More information is available in the Contributing guidelines.

Update your local copy (git pull)
Make a branch (git checkout -b <branch name>)
- the -b flag creates a new branch, rather than checking out an existing one
Make your edits
View the edited files (git status)
View your changes (git diff <file(s)>)
- changes can be reverted (git restore <file(s)>)
Stage the file(s) (git add <file(s)>)
- staged files can be un-staged (git restore --staged <file(s)>)
- if you have multiple changes in a file, but only want to stage some of them in this commit, use git add -p to mark which chunks you want to stage.
Commit the staged files (git commit -m "<message>")
- leave off the second double-quotes to write a multi-line commit message
  - be careful using certain punctuation when doing this (e.g. backticks)
- or, leave off the (-m "<message>") entirely to write your commit message in a text editor
- or, use composer commit to use Commitizen
- if you haven't pushed them, commits can be undone (git reset --soft HEAD~<num of commits to undo>)
Once you're ready, push your local commits (git push)
- for the first commit on a new branch, use (git push -u origin <branch>)

Pull Requests

On GitHub, create a Pull Request for your new branch to main
- if it's not ready yet, you can create a draft Pull Request that can't be merged until you un-draft it (but people can still review and comment on it)
Tag any related Issues in the PR
- if you want the PR to automatically close the Issues on merge, say 'Closes #' or 'Fix #'
If applicable, assign the PR to a Project and/or Milestone
- Projects are grouping of Issues and PRs with a given theme/objective
- Milestones are target states and the Issues and PRs that are required to reach that state

Branches

You can delete local branches when you are done with them (git branch -d <branch name>)
You can also update your refs to reflect any remote branches that have been deleted (git fetch --prune)
You can view all branches that you have a local copy of (git branch)
You can also view ALL branches, including those only on the remote (git branch -a)
You can switch from a branch to another (git switch <branch name>)

Rewriting history

NOTE: IF YOU DO NOT KNOW EXACTLY WHAT YOU ARE DOING, DO NOT MESS AROUND WITH THE GIT HISTORY

Miscellaneous

Fixing Git Bash autocompletion