Baby Steps to Avoid Problems for Beginners in GitHub

on
Photo by Jukan Tateisi on Unsplash

GitHub is a platform that enables collaboration. It brings people together to work on projects and documentation from anywhere in the world. When I was new to GitHub, resolving errors was a painstaking process that sometimes resulted in me needing help from colleagues. However, whenever I ask for help, I always make sure to learn the rationale behind the solution to make sure that I can use it to help others in the future.

Basic Steps

The following is the basic approach that I follow on a day-to-day basis when working with GitHub.

  1. Navigate to the Git branch that you want to use.
    Format:
    git checkout <branch-name>
    Example:
    git checkout master-1
  2. Update your local Git branch before making any changes.
    Format:
    git fetch upstream
    git merge upstream/<upstream-branch>
    Example:
    git fetch upstream
    git merge upstream/master
  3. Make the required changes.
  4. Save the changes locally.
    Format:
    git add <file path or folder path>
    git commit -m “<commit message>”
    Example:
    Let’s assume that you are updating some content related to the pages in the create-streaming-api folder.
    git add en/docs/design/create-api/create-streaming-api/
    git commit -m "Revamping the streaming API content"
  5. Update your local Git branch after adding local changes.
    Format:
    git fetch upstream
    git rebase upstream/<upstream-branch>
    Example:
    git fetch upstream
    git rebase upstream/master
    NOTE: You can sometimes face some errors when executing the rebase command.
    • If your local branch is not too outdated, then it will be very straightforward to resolve these errors.
    • If your local branch is very outdated, it will be more complicated to resolve these errors. Therefore, skip the rest of the instructions and move to the Workaround to expedite the troubleshooting process.
  6. Push your changes to your remote repository.
    Format:
    git push <your-remote-branch> <local-branch-name>
    Example:
    git push Mariangela master-1
  7. Create a pull request (PR) to send your fix to the upstream GitHub repository.

Workaround

The basic logic for this approach is that you will not face major rebasing issues if your local branch is up-to-date with the upstream branch. Therefore, to get out of this mess you can simply create a brand new branch and reapply your changes in that branch as follows:

NOTE: It is assumed that you moved to these instructions after step 5 in the Basic Steps.

  1. Abort the GitHub rebase process.
    git rebase --abort
  2. Note down the commit IDs that correspond to the new changes you worked on in the previous GitHub branch.
    git log
  3. Create and move to a new branch that corresponds to the same upstream branch.
    Format:
    git checkout upstream/<upstream-branch> -b <new-branch>
    Example:
    git checkout upstream/master -b master-2
  4. Update your local GitHub branch before adding local changes.
    Format:
    git fetch upstream
    git merge upstream/<upstream-branch>
    Example:
    git fetch upstream
    git merge upstream/master
  5. Apply your changes one by one to this branch.
    Make sure to apply the commits in the order in which you originally added them.
    Format:
    git cherry-pick <commit-ID>
    Example:
    git cherry-pick f1c0dc890d6a0d92e181fab84deedb777e398ccf
  6. Resolve any merge conflicts locally.
  7. Update your local Git branch after adding all the local changes.
    Format:
    git fetch upstream
    git rebase upstream/<upstream-branch>
    Example:
    git fetch upstream
    git rebase upstream/master
  8. Push your changes to your remote repository.
    Format:
    git push <your-remote-branch> <local-branch-name>
    Example:
    git push Mariangela master-2
  9. Create a pull request (PR) to send your fix to the upstream Git repository.


I hope that this blog post will come in use to some of you who are just starting off with GitHub. Please do not hesitate to share any tips and tricks in the comments section below so that I together with the others will be able to benefit from it.


Acknowledgments


A huge thank you goes out to Bhathiya Jayasekara for introducing me to the above mentioned workaround.

Comments

Post a Comment