Add workflow and getting started tips

Ben Goldsworthy 2021-04-17 00:27:43 +01:00
parent 6767900bfe
commit 694a4de113

@ -1,4 +1,50 @@
[Git][git] is the version control tool used for this project.
[Git][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)
1. Clone the repo. (`git clone git@github.com:markcheret/footnotes.git`)
1. View the available branches (`git branch`)
1. 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
1. TODO: Add SVN details to your Git config
# Workflow
More information is available in the [Contributing guidelines][contributing].
1. Update your local copy (`git pull`)
1. Make a branch (`git checkout -b <branch name>`)
- the `-b` flag creates a new branch, rather than checking out an existing one
1. Make your edits
1. View the edited files (`git status`)
1. View your changes (`git diff <file(s)>`)
- changes can be reverted (`git restore <file(s)>`)
1. Stage the file(s) (`git add <file(s)>`)
- staged files can be un-staged (`git restore --staged <file(s)>`)
1. 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>`)
1. Once you're ready, push your local commits (`git push`)
- for the first commit on a new branch, use (`git push -u origin <branch>`)
# Rewriting history
@ -7,4 +53,5 @@
- [Splitting commits](https://stackoverflow.com/a/6217314/4580273)
- [More detailed rewriting info](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History)
[git]: https://git-scm.com/
[git]: https://git-scm.com/
[contributing]: https://github.com/markcheret/footnotes/blob/main/CONTRIBUTING.md