Git'ing started with git and Github

This is just a BASIC cheatsheet for a PR based workflow using git and GitHub, geared towards new users of git and GitHub. If you are a new user, I HIGHLY recommend you skip to the end and review the Recommended Resources, which includes a sample GitHub repo you can clone and which will guide you through using GitHub.

• Basic PR workflow
  • 1. Starting new work
  • 2. Coding/scripting/hacking
  • 3. Pull request in GitHub
  • 4. Repeat Sections 1-3 as needed
  • 5. Release (as needed)
• Recommended Resources

Basic PR workflow

1. Starting new work

1. Check what branch you are on and whether you have changes that you might need to carry over to a new branch

git status

2. If you are NOT on main, AND you have changes to carry over, this will hide them in a stash temporarily:

git stash

3. If you were NOT on main, switch to it:

git checkout main

4. Make sure your local main has all the changes in the remote repo (GitHub, aka origin/main) so you have a clean starting point:

git pull

5. Create and switch to a new branch named NEWBRANCHNAME which will contain everything you want to PR. Usually a branch contains a single feature/improvement OR one or many bugfixes

git checkout -b NEWBRANCHNAME

6. IF you hid stuff in your stash before which you WANT to include in this branch, pop it off the stash:

git stash pop

2. Coding/scripting/hacking

Do the work!

1. Edit files, trying to keep edit/save blocks to RELATED changes .
2. Test the changes, take some screenshots while you do as these will go in your PR!!
3. IF you do NOT have a linter pre-commit hook OR you have a backlog of linting to clean up, run your linter now (shellcheck, hadolint, markdownlint-cli) and at least clean-up the function/areas you were working in. Test one more time.
4. Add your changes to the Index:

git add FILENAMES

5. Commit files to your LOCAL branch with a useful description, including any relevant Issue IDs. See Keywords in Issues and PRs for how.

git commit -m "Resolves #123. BRIEF_DESCRIPTION"

6. Push your commit to your remote branch (aka origin/NEWBRANCHNAME on GitHub):

git push

git push NEWBRANCHNAME origin  # If your config does not automatically push to origin

7. Repeat this block for more commits on this branch.

3. Pull request in GitHub

1. From the Pull Request tab, there should be a banner with NEWBRANCHNAME, asking if you want to create a PR - click that button! If not, there is a New button somewhere on that page: Base: main , Compare: NEWBRANCHNAME
2. Name this branch something useful, as the title will be used in the Autogenerated Release Notes.
3. Make some words to describe what it is and how you tested it! Drop some screenshots for evidence. Here's a nice simple example of how I do it on my own: hdub-tech/bitwarden-directory-connector-containers#24
4. Assign a reviewer!
5. After it is Approved, click the merge button to merge your branch changes into origin/main (remote)
6. Make sure any related Issues are closed.

4. Repeat Sections 1-3 as needed

5. Release (as needed)

Important

You do NOT need to cut a release for every closed issue or PR! Do things based on your timelines and rules.

TODO: Flesh this out

---

Troubleshooting

Undo'ing changes

TODO: Flesh this out then add to ToC

Merge conflicts

TODO: Flesh this out then add to ToC

---

Recommended Resources

1. Interactively learn GitHub skills
2. GitHub Practice repo
3. Fork and pull request practice repo
4. GitHub docs: Best Practices for repositories
5. GitHub's keywords for linking commits, issues, and PRs
6. git documentation (The git man pages are also found using git --help or git SUBCOMMAND --help or man git or man git-SUBCOMMAND )