A Git workflow with branches

Hover over different portions of the code for more information.

  1. Make sure your local respository is up to date with the remote repository.

    git fetch origin
    git merge origin/main
  2. Create a branch for your changes and move to it, or move to an existing branch.

    git checkout -b mybranchname or git checkout mybranchname
  3. Edit and make changes to the code in your repository.

  4. Commit changes.

    git status
    git add <filename>
    git commit -m "a short note about the changes you made"
  5. Make and commit more changes, repeating step 4 and 5, as desired.

  6. Get any changes from the main branch in the remote repository that were made by other people while you were working.

    git fetch origin
    git merge origin/main
  7. Resolve any conflicts that occurred during the merge.

  8. Push your changes back to the remote repository.

    git push -u origin mybranchname
  9. Make a pull request on GitHub, including a message when prompted.

  10. Make sure your code passes all quality control checks that you've included on GitHub.

  11. Wait for another member of your team to go to GitHub, review your changes, approve merging them into the main branch, and delete the remote branch once this process is complete and the branch is no longer needed.

  12. If your changes were successfully merged, and you're all done with this branch, you can move back to the main branch and delete the old branch locally.

    git checkout main
    git branch -d mybranchname

    To finish cleaning up, repeat step 1, taking the changes you pushed and merged remotely and merging them into to your local main branch.

    git fetch origin
    git merge origin/main

More information:

Atlassian's Git cheat sheet and Tutorials, including their Feature Branch Workflow tutorial are excellent.

(Optional) A few other questions and concerns

Perhaps you were so excited to start editing that you forgot to get any new updates from the remote repository before you started, and you forgot to check out a branch or fetch and merge. That is, you skipped steps 1 and 2 above, and moved straight to step 3, editing your code. To recover from there, you can insert the following steps before you commit.

  1. Tuck away the changes you made for safe keeping.

    git stash
  2. Do the fetch and merge and/or branch checkout that you meant to do before you started.

    git fetch origin
    git merge origin/main

    and/or

    git checkout -b mybranchname or git checkout mybranchname
  3. Retrieve the changes that you tucked away for safe keeping now that you can put them on top of up to date code and in the proper branch.

    git stash pop
  4. Proceed with commiting, etc. as described in step 4 and onward, above.

  5. Omitting the branching and pull request portions of the flow described above, and working only on the main branch, will simplify the process. The simpler process below might be sufficient for your needs, at least for a while. If you find that quality control and resolving conflicts is becoming unwieldy, especially as your project grows, you might find the extra steps of the branching model above are worth it.

    1. Make sure your local respository is up to date with the remote repository.

      git pull --rebase origin/main
    2. Edit and make changes to the code in your repository.

    3. Commit changes.

      git status
      git add <filename>
      git commit -m "a short note about the changes you made"
    4. Make and commit more changes, repeating the previous two steps, as desired.

    5. Make sure you're up to date with any changes anyone else has pushed to the remote repository while you were working (if necessary/applicable).

      git pull --rebase origin/main
    6. Push your changes back to the remote repository.

      git push origin main

    Sure. Using rebase instead of merge will ensure a linear history, so you can choose this option if that's important to you. For reference in that case, below is a version of the workflow with the same basic structure as was presented above, but using rebase instead of merge. There is a nice explanation of merging vs. rebasing here.

    1. Make sure your local respository is up to date with the remote repository.

      git fetch origin
      git rebase origin/main

    2. Create a branch for your changes and move to it, or move to an existing branch.

      git checkout -b mybranchname or git checkout mybranchname
    3. Edit and make changes to the code in your repository.

    4. Commit changes.

      git status
      git add <filename>
      git commit -m "a short note about the changes you made"
    5. Make and commit more changes, repeating step 4 and 5, as desired.

    6. Get any changes from the main branch in the remote repository that were made by other people while you were working.

      git fetch origin
      git rebase origin/main
    7. Resolve any conflicts that occurred during the merge.

    8. Push your changes back to the remote repository.

      git push -u origin mybranchname
    9. Make a pull request on GitHub, including a message when prompted.

    10. Make sure your code passes all quality control checks that you've included on GitHub.

    11. Wait for another member of your team to go to GitHub, review your changes, approve merging them into the main branch, and delete the remote branch once this process is complete and the branch is no longer needed.

    12. If your changes were successfully merged, and you're all done with this branch, you can move back to the main branch and delete the old branch locally.

      git checkout main
      git branch -d mybranchname

      To finish cleaning up, repeat step 1, taking the changes you pushed and merged remotely, and merging them into to your local main branch.

      git fetch origin
      git rebase origin/main
    1. Before you start, make that sure any unrelated changes you were working on previously are committed to some appropriate branch.

    2. Make sure you have all the latest info about any changes anyone else has pushed to the remote repository (including your collaborator's great new remote branch!).

      git fetch origin
    3. Make a local copy of the branch that your collaborator started and pushed and move to that branch.

      git checkout -b my-new-branch-name origin/my-collaborators-remote-branch-name
    4. You should now see the version of the code from your collaborator's branch when you look at your files locally. Edit the files to make whatever contributions you were hoping to make.

    5. Commit changes.

      git status
      git add <filename>
      git commit -m "a short note about the changes you made"
    6. Push your changes up to the remote branch that your collaborator started.

      git push origin HEAD:my-collaborators-remote-branch-name
    7. If desired, move back to the main branch, or whatever branch you want to work on next.

      git checkout main