Skip to content

Workflow and Git guide

Jump to bottom
Daria Derecha edited this page Mar 30, 2020 · 2 revisions

Contents

Set up

  1. Fork the repo to your own GitHub account.
  2. Clone it onto your local working environment. 
    git clone https://github.com/[Your GitHub Username]/Democrify.git
  3. Set the repo to track upstream to the main repo. 
    git remote add upstream https://github.com/Sapphire-Snail/Democrify.git
  4. You can use git remote -v to check the upstream has been added.

You are now good to start working on stuff! Here is a simple guide to git if you have not used it before.

Working on an issue

  1. Make a branch on your local repo using git checkout -b <name-of-branch>. Name your branch appropriately, so it is descriptive of a problem you are working on, e.g. homepage-design or voting-count-fix

  2. Work on the feature on your branch, making commits (with git add and git commit) as needed. You can use git branch to list all branches and git checkout <branch-name> to navigate between branches. You can git push your branch periodically and the commits will appear on your fork.

  3. Update your fork's master branch regularly. See: Updating your fork.

  4. When you are ready to merge your code into master, rebase your branch on top of the most recent version of master so your commits are on top of the most recent version of the code. See: Updating your fork.

  5. Test your branch works as expected and it builds/all tests pass. Push your changes up to your fork with git push. If you rebased, you will need to do a force push git push -f. If it's the first time pushing you need to set the remote branch but git should tell you the command to do it.

  6. Open a pull request on GitHub from your branch to the master branch of Sapphire-Snail/Democrify. Make sure to put "fix #123" or "closes #123" in the description or a commit message so it automatically links and closes the issue.

  7. Get at least 2 people to do a code review. Any fixes you push up from your local branch should be added to the PR.

A nice way to get your changes after they are merged is to sync your master with upstream again. To do this, checkout your master branch and use git pull upstream

Useful git commands

Updating your local copy

Update your local fork with the main code often. You can sync your master with the upstream with:

# go to master branch MAKE SURE YOU DON'T HAVE UNCOMMITTED CHANGES
git checkout master

# get the latest changes
git fetch upstream

# apply the changes onto your master
git merge upstream/master

# (optional) push up these changes to your fork on GitHub
git push

You can also use git pull upstream master, which is a shortcut for the fetch and merge.

To update your branch so your commits are now on top of the latest master do:

# go to your branch
git checkout <branch-name>

# get changes from master onto branch
git rebase master

# push your newly-based branch to your fork
git push -f

Be aware that if other people have also worked from your branch, this will cause problems and generally isn't recommended (but there are ways to handle it safely).

Stashing

  • If you want to save your work in progress, you can either use git stash or put it onto a local branch git checkout -b wip/temp-branch.
  • Get your stashed work back with git stash pop.

Inspecting your repo

  • git status is extremely useful.
  • git diff is pretty useful. It can tell you the differences between commits, specific files on commits, or branch heads.
    • git diff <filepath> tells you what changes you've made to a file that you haven't yet added
    • git diff <commit1> <commit2> tells you what the differences are between commit1 and commit2, in terms of what changes you'd have to make to get from commit1 to commit2. For example, git diff HEAD~1 HEAD tells you the changes that were made by the commit before the most recent (HEAD is the most recent, HEAD~1 is the one before).
    • git diff <branch1> <branch2> compares branches the same way as commits (branches are just labels for commits anyway).
  • git log shows you the commit history of your current branch (which will trace back to and include master).
    It can be a little confusing if you've merged anything in. To get a visualisation of your commit history, try out git log --graph --oneline. If you want to see all your branches, add the --all option.

Accessing other people's work

Adding their repo

Your local repo is set up with two remotes, origin being your fork and upstream being the base repo. These remotes are simply references to other copies of the repo that we've told git about. So if you want to see your colleagues' branches, you need to add their forks as other remotes.

You can do this with git remote add <name> <url>. <name> can be anything you want - the person's GitHub username is probably most useful. For instance, if you wanted to see Vanessa's branches, you'd do

git remote add vee-christella https://github.com/vee-christella/A1.git.

Now if you do git remote -v (to list the remotes verbosely) you'll see something like:

Checking out branches

Now we can download the data for all the branches on her fork and take a look at all the branches we have access to

git fetch vee-christella

git branch -al

Say you want to look at feature/homepage-transaction-list. You'd do

git checkout --track remotes/vee-christella/feature/homepage-transaction-list

This will set up a branch on your local repo (not your fork) with the same name and copy all the commits. --track tells git that you want to use the remote branch (the one on Vanessa's fork) to retrieve updates. So if she pushes more commits to her fork on that branch, you can do git pull with feature/homepage-transaction-list checked-out and it will update the branch just like it usually does.

If you wanted to do some work on top of that, you can branch from it (you'll need to use a different name for your branch). If your colleague does make more commits, you'll probably want to rebase. Follow a similar workflow for updating from the base repo:

# Checkout your colleague's branch
git checkout feature/homepage-transaction-list

# Get the latest changes
git pull

# Go back to your branch
git checkout <branch-name>

# Rebase
git rebase feature/homepage-transaction-list
Clone this wiki locally