Before starting any work, create a new branch off of the base branch your changes will be submitted to.
E.g. if you are working on a bug, your base branch would be main; if you are working on a feature, your base branch would be that feature's branch.
It is good practice to give the branch a name that is relevant to the work being done.
E.g. fix-cli-printing-bug
, add-component-of-feature
, etc.
-
Switch to the base branch
git switch main
-
Update the base branch
git pull
-
Create a new working branch
git switch -c WORKING_BRANCH
Feel free to commit and push changes as often as you'd like to save any progress you've made.
As a general rule, try to make your commits as small and logical as possible. Leaving a trail of your thoughts for reviewers to read is the goal.
-
Add and commit changes
git add FILES git commit
-
Push changes to GitHub
git push origin WORKING_BRANCH
-
Commit and pushed any changes you want reviewed.
git add FILES git commit git push origin WORKING_BRANCH
-
Go to your repository's GitHub page.
-
Create a Pull Request (Make sure to the base branch on your Pull Request is correct!)
-
Add reviewers (GitHub might make reviewer suggestions, add those as well).
-
Wait for comments and requests.
Reviewers will undoubtedly have comments and/or make requests for your changes.
For each request, add a new commit to address that request, then push your new commits.
Every time you push, the Pull Request will be automatically updated and reviewers notified.
Note You do not need to push each commit. Making several commits and pushing once is fine.
Warning Do NOT rebase or amend commits, i.e. no force pushes please.
Once you have gotten enough approvals, use the Squash and Merge button to prepare your changes for merge.
Warning Do NOT merge other people's Pull Requests
The Squash and Merge button will present you with a text box to write a merge title and message. Check that the merge title and message match your PR title and message.
Note Try to make your commit message informative and helpful.
General rules for commit messages:
- For bug fixes, explain why this change fixes the bug.
- For feature work, explain how this part of the feature is supposed to work.
If you'd like to read more about writing good commit messages check out this blog post.
Now that you're finished, it's time to get back to work!
To start new work, follow the same steps as before:
-
Switch to your base branch
git switch main
-
Pull the latest changes
git pull
Warning If you get a merge conflict or git tries to create a merge commit, see below
-
Create a new branch for your work
git switch -c NEW_WORKING_BRANCH
Note, you do not need to do anything to your old branches, but if you do want to cleanup old Pull Request branches, checkout this Stack Overflow answer.
If you are having trouble running git pull
on a base branch like main
, it may be that you accidentally made a commit on the base branch before creating your
working branch.
To fix this, create a tag on your current main branch to make sure no commits are "lost"
git switch main
git tag USERNAME/save-main
Then re-checkout the main branch
git checkout USERNAME/save-main
git branch -D main
git fetch
git switch main
As long as there are no merge conflicts (which GitHub will warn you about), there is nothing you need to do.
The Squash and Merge button will handle the divergence like magic.
Use Git's merge command to merge
the base branch into your working branch, resolve all conflicts, and push.
git switch main
git pull
git switch WORKING_BRANCH
git merge main
Resolve merge conflicts
git commit
Same as above, use Git's merge
command to update your working branch.
git switch main
git pull
git switch WORKING_BRANCH
git merge main
In this case, create a branch off of your Pull Request branch and start working from that.
git switch PR_BRANCH
git pull
git switch -c NEW_WORKING_BRANCH
FYI, you can use a Draft Pull Request for work that is not yet ready.
This is identical to the solution above, except you'll need to use that user's Pull Request branch before creating your new branch.
git fetch
git switch COWORKERS_PR_BRANCH
git pull
git switch -c NEW_WORKING_BRANCH
Make sure to keep your branch up-to-date with changes from that user's Pull Request by periodically merging their branch into yours.
git pull origin COWORKERS_PR_BRANCH
This is identical to the last step of the solution above. You just pull the other user's Pull Request into an existing branch instead of creating a new one.
git pull origin COWORKERS_PR_BRANCH
Sometimes it makes sense for a reviewer to push changes to your Pull Request. This is fine, but you will need to pull those changes locally before you will be allowed to push any of your changes.
With your working branch checked out, use the pull
command with the remote and branch parameters to pull changes from your Pull Request branch.
git switch PR_BRANCH
git pull origin PR_BRANCH
Come on over to the #help_git Slack channel and someone will help you out :)