Skip to content

8 GitHub Cheat Sheet

Jump to bottom Edit New page
Marco edited this page Aug 25, 2014 · 78 revisions

How to sync my fork with source project ?

git remote add upstream https://github.com/pi-engine/pi.git # Assigns the original repo to a remote called "upstream" = creates a shortcut

How to sync the upstream with my fork ?

git fetch upstream # grabs the branch changes from the source project repo not present in your fork repository, without modifying your local files. Allows you to review first.

git fetch upstream --tags #If the project has tags that have not merged to your develop

git checkout develop //checkout your develop branch

git merge upstream/<branch-name> # merge fetched changes from the develop branch of upstream into the branch you checked out (develop i.e. your forked repo). So it becomes git merge upstream/develop in case of the develop branch.

git push origin develop //if you want to push your updated develop into origin

To know more GitHub Help /working with upstream

How to fix my upstream that does not work anymore ?

In most cases, it's because you deleted your fork. Upstreams are not deleted when deleting forks, you have to Reset it.

git remote -v : list all remotes urls for origin and upstream, for each fetch and pull methods

git remote set-url upstream [YOUR URL] : set the upstream url (source project repository) again

What are upstream, origin, local ?

  • upstream : the original project repo on github `https://github.com/pi-engine/pi' = source project files
  • origin : your forked repo on github https://github.com/<your-account>/pi = forked files
  • local : your clone of your forked repo, on your laptop/desktop = working files

your goal is to follow up changes across repos, and apply them when needed after validation, to be up to date.

What is a rebase ?

If there are any commits on the destination branch that aren't on your feature branch then you should rebase to avoid a merge commit.

  • You can check for such commits using git log ..upstream/develop
  • Make sure that you're on your develop branch: git checkout develop
  • Rewrite your develop branch so that any commits of yours that aren't already in upstream/develop are replayed on top of that other branch.
    • This rewrite the history of your develop branch.
    • This replays your commits on top of the new commits from the destination branch so that the merge can be a 'fast-forward'.

git rebase upstream/develop

NB : If you don't want to rewrite the history of your master branch (for example because other people may have cloned it) then you should replace the last command with git merge upstream/develop

  • Force the push in order to push it to your own forked repository on GitHub

git push -f origin develop

Rather than having to rebase your own master branch to ensure you are starting with clean state, you should probably work on a separate branch and make a pull request from that. This keeps your master clean for any future merges and it stops you from having to rewrite history with -f which messes up everyone that could have cloned your version. Rewriting history of shared repositories and branches is something you should NEVER do.

What is squash command? Often you commit several commits to your forked repo. Before pulling a request to origin, you want to group commits per subjects into well-labelled commits.

  • list all commits made : git log
  • squash the last 3 commits into one : git rebase -i HEAD~3 (make an interactive rebase)
  • this will list the latest 3 commits in text editor
    • pick df94881 commit1
    • pick a7323e5 commit2
    • pick 3ead26f commit3
  • change to
  • pick df94881 commit1
  • squash a7323e5 commit2
  • squash 3ead26f commit3
  • save/quit : text editor will ask for description
  • save/quit again
  • git log to verify your changes
  • git push -f : force push to your fork repository

NB Changing history on public repos is a bad thing Rewriting history and using git push -f on a branch that, potentially, someone else has already cloned is a bad thing - it causes the repository's history and that of the checkout to diverge. However, amending the history of your fork to correct the change you are proposing to be integrated into a repository - is a good thing. As such have no reservations squashing "noise" out of your pull requests.

How to make a pull request?

  • STEP 1 : git push origin newfeature : push your branch code to your fork (this is normally made by your GitHub tool)
  • STEP 2 : you can create it directly from github.com from your fork (NB you can play with switching the base to make a Pull Request from your fork to origin , or from the origin to your fork)

How to select what commit i add in a pull request (cherry-picking)?

You need to create a branch and then select the commits to add into that new branch

  • git fetch upstream //get the latest changes from the original repo
  • git checkout -b my_new_feature upstream/develop //create a new branch, starting from the develop branch of the original repo
  • git cherry-pick WHATEVER_COMMIT_ID_I_WANT //select the commit I want and add it to this new branch
  • git push origin my_new_feature //push the new branch to my fork

How to update an open Pull Request ?

In most case, the team accepts your pull request except few commits.If the Pull Request is still opened :

  • easy solution : simply creating another pull request
    • You just have to fix or to revert and create a new pull request,
    • that will update automatically the opened existing pull request. it will add your commits to to existing open pull request.
  • cleaner solution : squashing
    • Squashing can be usefull to merge 2 commits from a pulled but not merged Pull Request.
    • Your pull request will be updated with the squashed commit
    • It will contain a single commit, incorporating all changes previously split into several commits.
  • another solution : if you change your pull request branch locally to remove/change commits, you can then "force push" the branch and the pull request will update and use whatever commits you just pushed. git push origin newfeature --force

How to work with branches ?

Switch off of the 'master' branch and onto a different branch for your new feature. It's important to do this because you can only have one Pull Request per branch, so if you want to submit more than one fix, you'll need to have multiple branches.

  • Make a new branch : git branch newfeature
  • Switch to it : git checkout newfeature
  • (simplified command : git checkout -b newfeature) : creates and switch with one line

NB : to Confirm you're in this branch : git branch.

Generally you want to keep your local develop branch as a close mirror of the upstream develop and execute any work in feature branches (that might become pull requests later).

When you want to share some work with the upstream maintainers :

  • you branch off master, create a feature branch

    • git checkout -b feature-x

  • some work and some commits happen

  • some time passes

  • rebase (instead than merge) to make sure the upstream has a clean set of commits (ideally one) to evaluate:

    • git fetch upstream
    • git rebase upstream/develop

  • when you’re satisfied you push it to your remote repository.

    • If you need to squash a few commits into one you can use the awesome rebase interactive at this point.
    • After the above, publish your work in your remote fork with a simple push:
      • git push origin feature-x

  • Then you generate a pull request to the source project

  • You get some feedback from the upstream maintainers. You have a few options if you have to update your remote branch feature-x after you published it. There are few options :

    • Option 1: Create a new branch altogether with the updates from you and the upstream.
    • Option 2 : merge the updates from upstream in your local branch which will record a merge commit. This will clutter the upstream repository.
    • Option 1(preferable) : Rebase your local branch on top of the updates from upstream and do a force push onto your remote branch: git push -f origin feature-x

How to delete a branch?

  • you can do directly from GitHub tool and from github.com
  • for sure you will need the command line
    • STEP 1 delete the local branch git branch -d newfeature (or git branch -D newfeature to force deletion if your newfeature branch hasn't been merged yet)
    • STEP 2 : delete the remote branch
      • in this case, you will have a warning : "warning: deleting branch that has been merges to , but not yet merged to HEAD", so you have to delete also this branch in origin
      • git push --delete origin newfeature or git push origin :newfeature (notice the blank position on the left of the : )
    • STEP 3 : you need also to Prune the obsolete local remote-tracking branch origin/newfeature
      • git fetch origin --prune will automatically delete any local remote-tracking branches of remote branches that no longer exist on the remote

How to update working branch with upstream?

  • checkout to your branch
  • it will be told to you that you need a git pull and it will fast-forward the code

other tips

  • pull is a combination of the commands fetch and merge
  • sometimes it's quicker to delete his fork and commit again
  • you can only have one PR open per repository : so it's better to work with working branches

Need something?

Other good resources

Add a custom footer
Add a custom sidebar
Clone this wiki locally