Skip to content

Workflow and git guide

Jump to bottom
kaplunket edited this page Apr 4, 2020 · 35 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]/A2.git
  3. Set the repo to track upstream to the main repo. 
    git remote add upstream https://github.com/se701-group6/A2.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>. Prefix the name of your branch with feature, bug, docs, for example like feature/split-bills-evenly or bug/not-able-to-press-button.

  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 SOFTENG701/A1. Make sure to put "fix #123" or "closes #123" in the description or a commit message so it automatically links and closes the issue. Your PR will automatically be labelled as Frontend or Backend, based on which folder you've made changes in.

  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.

  8. Have another team member merge the PR when it is ready. You must have at least 2 other team members approve your PR to have it merged. Also note you can annotate the PR.

To raise a new issue see Issue Raising

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 things

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).

With pictures

Having set up your repo, made some commits and pushed your branch to your own fork on GitHub, you now have a situation like this:

Suppose someone merges in a PR on the base repo, adding one more commit:

We want to run git fetch upstream && git merge upstream/master (or same as git pull upstream master). This is the result

Now if you want to update your fork as it is on GitHub, simply git push on master:

When updating our local branches, we do a rebase and then push. The result:

Accessing other people's work

See here

Advanced Rebasing

  • An interactive rebase is very useful to clean up your code before pushing if you have bad commit messages or want to squash commits. Use git rebase -i HEAD~<number-of-commits>. For example, if I wanted to squash the last 2 commits I would use git rebase -i HEAD~2. Then you can follow the commands that appear on the terminal (feel free to ask for help if you get lost rebasing or Google can help).

  • If you've got commits that you want to throw away, or you've based your branch off somewhere other than master, you'll need to use rebase with the --onto option.
    First, make sure you're checked-out the branch you want to rebase. The form is git rebase --onto <newbase> <oldbase>. Newbase is wherever you want the new base to be (duh). This could be any commit or branch, but most likely you'll want it to be master. Oldbase tells git where you based your branch off of originally, or alternatively where you want to start discarding.
    Check out the --onto section of the git help file on rebasing for a simple example (scroll down to where you see the graphs)

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.

Tips

  • Don't ever rebase and push if someone else could be working on the code. It is probably ok to rebase and push to your fork before you open a PR but better to avoid this to be safe.

  • If you ever want to work on the wiki locally or add images to it, you can pull down the wiki as a git repo. Just add .wiki.git to end of the repo name like:

    git clone https://github.com/SOFTENG701G1/A1.wiki.git

  • Here is a simple guide to git if you have not used it before.

Processes

Design

Code

Testing

Clone this wiki locally