Skip to content

Git Workflow

Jump to bottom
stiartsly edited this page Sep 19, 2018 · 2 revisions

Git Workflow Guide

Tasks

The main categories of carrying task would be listed below:

  • Feature (feat)
  • Bugfix (fix)
  • Test (test)
  • Docs (docs)
  • Vendor (vendor)

Principles

The following principles must be followed during your whole project development:

  • The development of whole project is driven by a number of taskes;
  • Each task must be working on it's own branch exclusive to others;
  • The only way to update master branch is through pull request.

Workflow

###1. Create branch from master

Create a new branch from master with appropriate name on Github according to the following rules.

If your task is to:

  • develop a new feature or make improvement for the feature, then use prefix feat;
  • fix an issue, then use prefix fix;
  • add a tests, then use prefix test;
  • add a documentation, then use prefix docs;
  • upgrade dependancies, then use prefix vendor.

If your changeset doesn't fall into one of these categories, then use prefix other.

After that, try to address what part or module of codebase this branch is working on. For example, if you are working on "group" feature, then the branch name feat_group would be acceptable. If your try to ammend some comments to README.md, then use "docs_readme as your branch name.

Please try to keep branch name around or under 20 characters, which would keep things a little cleaner overall. And also try to avoid putting issue numbers in branch names.

###2. Checkout branch

After owning your new branch on Github, you have to pull it and checkout this target branch:

$ git pull
$ git checkout feat_group

or you can directly clone a local repository from remote target branch:

$ git clone -b feat_group YOUR-REMOTE-GIT-REPOSITORY

After that, use the command to check your working branch name:

$ git branch

or see more branches to switch between them:

$ git branch -a -vv

3. Working on branch

As you have your local branch, keep working on this branch to implement desired feature or to fix the issue by using git add and git commit comments.

$ git add foo.cpp
$ git add bar
$ git commit -m "This is commit comment of example"

Alternatively, you can use the following command to add all changes of tracked and untracked files.

$ git add --all
$ git commit -m "This is commit comment of example"

Or to add all updates of tracked files:

$ git add -u
$ git commit -m "This is commit comment of example"

You are strongly recommended to commit the itermediate codebase updates with comments prefixed with "WIP".

4. Squash branch

When you have a bunches of commits of carrying out the whole feature or bugfix on working branch, use log command to review a few of last commit logs:

$ git log --graph --decorate --all --oneline -20

Then try to squash all commits with "WIP" comments. Here as an example, to squash 10 commits back from HEAD.

$ git rebase -i HEAD~10

Beaware, squashing commits is an interective process to edit actions, where all pick actions from line 2 to last line would be changed to "squash", and recomment your appropriate commit message.

5. Rebase branch from master

After squashing your commits, you have to rebase it from master in case that the master has moved forward with recents commits from other feature or bugfix branches.

Try to update master branch before rebase your branch.

$ git fetch --all -p

Then you can rebase your feature branch onto upstream/master branch. For example, use the following command to rebase last 2 commits of feature branch onto master:

$ git rebase --onto upstream/master HEAD~2 feat-branch

Or just simply use command to rebase all last commits from feature branch onto master.

$ git rebase master

If the updates of your commits on feature branch has conflicts with master, the rebase process would stop and wait for you to edit it and clean these conflicts. You can use the command to show what files has been conflicted:

$ git status

After cleaning conflicts and then git add these updates, then use the command to continue rebase process:

$ git rebase --continue

6. Push branch to remote

When every thing is settled for your feature branch, then run the command to push it to remote branch.

$ git push -u origin feat-branch

The process of pushing your feature branch would fail if you squashed commits of remote feature branch, in which case the remote branch would think commits lost in your push updates.

You can push updates with --froce options after check:

$ git push -f -u origin feat-branch

7. Pull request

After pushing your updates, then you can check it if pushing succeeds or not by reviewing commit logs of feature branch. Then click New pull request button to open a pull request to master branch.

To create a pull request, you have to edit the title and to commit appropriate messages as well as to set the reviewers for it. Then the left thing for you is to wait for reviewer to review the pull request and merge it into master branch or reject it.

If the pull request is rejected, then you have refine your updates according to reviewer's suggest, and conduct previous steps again so as to make another push request.

8. Delete branch

After your pull request have been merged into remote repository, then delete this branch if you stop to work on it.

$ git checkout master
$ git branch -D feat-branch
$ git push --delete origin feat-branch

Clone this wiki locally