first commit

docs/git.md

@@ -0,0 +1,105 @@
+# Git
+
+* [GitHub Flow](https://dev.to/karmpatel/git-branching-strategies-a-comprehensive-guide-24kh) branching strategy is used.
+* Direct push to `main` branch is prohibited.
+* Only merges to the `main` branch via Pull Requests from `feature/...` or `bugfix/...` branches are allowed.
+* Tags are created for releases on the `main` branch.
+
+## Pull Request
+
+1. Ensure your main branch is protected, so that direct push is disabled.
+
+2. Update the local main branch.
+
+    ```bash
+    git checkout main
+    git pull origin main
+    ```
+
+3. Create a new branch, `feature/new-branch`, with a descriptive name and switch to it.
+
+    ```bash
+    git checkout -b feature/new-branch
+    ```
+
+4. Add any changes.
+
+    ```bash
+    git add .
+    ```
+
+5. Commit the changes with a message.
+
+    ```bash
+    git commit -m "new branch: create all boiler plate files"
+    ```
+
+6. Push the new branch, `feature/new-branch`, to the remote Gitea repository.
+
+    ```bash
+    git push origin feature/new-branch
+    ```
+
+7. Create a new Pull Request from `feature/new-branch` to the `main` branch.
+
+8. Review and Merge the new branch into the `main` branch.
+
+9. Switch back to the `main` branch.
+
+    ```bash
+    git checkout main
+    ```
+
+10. Pull the latest changes that include the merged PR.
+
+    ```bash
+    git pull origin main
+    ```
+
+11. Delete the local `feature/new-branch` branch.
+
+    ```bash
+    git branch -d feature/new-branch
+    ```
+
+12. Delete the remote branch after merging if Gitea did _not_ delete it.
+
+    ```bash
+    git push origin --delete feature/new-branch
+    ```
+
+13. Create a new branch for upcoming work, for example `feature/dev`.
+
+    ```bash
+    git checkout -b feature/dev
+    ```
+
+## Troubleshooting
+
+### Accidentally created a commit on local `main` branch instead of a feature branch
+
+1. Create a new branch pointing to the extra commit.
+
+    ```bash
+    git branch feature/new-branch
+    ```
+
+2. Reset the local `main` branch to match the remote `origin/main`.
+
+    ```bash
+    git reset --hard origin/main
+    ```
+
+3. Switch over to the new feature branch
+
+    ```bash
+    git checkout feature/new-branch
+    ```
+
+4. Push the new branch.
+
+    ```bash
+    git push origin feature/new-branch
+    ```
+
+5. Create a Pull Request.