Git Tips

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

1. Install Git (obviously)
2. Clone the repo. (git clone [email protected]:markcheret/footnotes.git)
3. View the available branches (git branch)
4. Set your user details:
   • git config --global user.name "John Doe" and git config --global user.email [email protected]
   • if you want to use a local username/email that is different to your global one, drop the --global option
5. TODO: Add SVN details to your Git config

Workflow

More information is available in the Contributing guidelines.

1. Update your local copy (git pull)
2. Make a branch (git checkout -b <branch name>)
   • the -b flag creates a new branch, rather than checking out an existing one
3. Make your edits
4. View the edited files (git status)
5. View your changes (git diff <file(s)>)
   • changes can be reverted (git restore <file(s)>)
6. 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.
7. 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>)
8. 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

1. 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)
2. Tag any related Issues in the PR
   • if you want the PR to automatically close the Issues on merge, say 'Closes #' or 'Fix #'
3. 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

1. You can delete local branches when you are done with them (git branch -d <branch name>)
2. You can also update your refs to reflect any remote branches that have been deleted (git fetch --prune)
3. You can view all branches that you have a local copy of (git branch)
4. You can also view ALL branches, including those only on the remote (git branch -a)
5. 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

• Splitting commits
• More detailed rewriting info

Miscellaneous

• Fixing Git Bash autocompletion