Git Workflow Guide

Git Workflow Guide

Introduction

Here is the basic development workflow and best practices to be followed for all development work using Git.

Important: If the project has both a dev and master branch, always work off the dev branch, otherwise work off the master branch. When in doubt, ask your lead :-)

Getting Rolling

You will either:

Clone a remote Git repository.
Initialize a new Project.

Cloning an Existing Project

git clone <git-remote-url> (target-name)

Note: If you want to rename the repository during cloning, you can provide a target name. This is optional and usually omitted.

Initializing a new Project

Do this only for a new Project you have created.

You might also want to add a Git ignore configuration file.

These steps will add all files to Git for tracking and commit them to be saved to the Git local repository.

cd <project-path>
git init
git add -A .
git commit -m "You commit message."

Note: You will need to create a new empty repository on Github or Bitbucket if you want to host the project remotely.

Things to be aware of

Never push directly to master or the development branches.
Always make changes in your feature-branch off development or master branch.

Tips:

Commit often and keep your commit changes small.
Do not commit large or multiple changes at once.
Do not commit unfinished work.
Format, lint and test before your commit.

Basic Git Workflow

Here are the following steps you will do in the Git development workflow.

Note: This is a simplified overview. The steps for rebasing or squashing and rebase not included here but should be followed in the order listed.

Steps (*)	Git Command
1. Switch to the dev or master branch.	`git checkout dev`
2. Perform a pull to get the latest changes.	`git pull --rebase`
3. Create a feature working branch.	`git branch <branch-name>`
4. Switch to feature-branch.	`git checkout <branch-name>`
5. Make code changes.
6. Add changes and new files to Git for tracking.	`git add <file>`
7. Perform a commit with the standard message format (See below).	`git commit -m "Type: Message"`
8a. Perform a rebase.	See below for steps.
8b. Perform a squash & rebase.	See below for steps.
9. Push changes up to remote and create a PR.	`git push origin -u <branch-name>`
10. Go to step 1.

House Cleaning: You will want to delete your feature-branch once the PR has been approved and merged. Always verify your changes were merge correctly upstream first! :-D

Steps for code changes

Get latest updates from development or master branch.

git checkout dev|master
git pull --rebase

Create your work branch then switch to it.

git branch <branch-name>
git checkout <branch-name>

You can perform both the steps above with this single command:

git checkout -b <branch-name>

Make code changes and then commit the changes to Git locally.

Check what has changed

If you want to see what files have changed, use the following command:

git status

Add changes to be committed

git add <filename> ...

You can add all "tracked" changes at once using:

git add -u

Note: A tracked file is a file you did a "git add" to.

Important: To track new files you created, use, "git add" as shown above.

Finally use, "git status" to make sure all changes have been added.

Commit changes

Only added files will be committed.

git commit -m "Type: Message."

Commit Message rules

type: description

(*) The CHANGELOG.md file will be auto-generated from Git commit messages, therefore it is important you follow "semantic commit message".

Examples

git commit -m "fix: Model data ingestion."
git commit -m "chore: Configuration update."
git commit -m "feat: New Cloud Storage support."
git commit -m "docs: Updated README."

Where the Type can be:

Type	Meaning
feat	A new feature being added.
fix	Bug fix, should contain a bug number for tracking.
edit	Minor coding edit, clean up, formatting.
refactor	Code refactoring.
config	Changing config or property value in code.
test	Test code changes, additions.
doc	Documentation changes.
style	Layout styling or formatting changes.
BREAK	Breaking change, result in a major version bump.

Before a Pull Request

First: Make sure you have committed your code changes to the working branch.

Important: Always rebase on your working branch, never perform a merge.

The following will fetch the latest changes from remote.
Apply your feature-branch changes onto the dev or master branch.
Fast-forward HEAD to the front of the commit chain.
Finally push your changes to Remote to create a pull-request.

Rebasing for a PR

git checkout <work-branch>
git fetch -p origin
git rebase origin/(dev|master)
git push origin <work-branch>

Thesse steps will move your changes into dev or master branch.

git checkout dev|master
git merge <work-branch> --ff

What happened: The rebase moves all of the commits from your work branch onto the tip of dev or master then applies your changes. This results in a linear commit history.

Before Rebasing

Below the working-branch is missing update from upstream committed by other developers.

We need to apply the new upstream changes to the working-branch.

After Rebasing

The HEAD pointer has fallen behind after rebasing.

Fast-Forwarding HEAD

Golden Rule of Rebasing: Never rebase on a public branch (A branch you did not create or do not own).

If there are rebase conflicts, you will need to manually resolve them. After you continue with the rebase.

git rebase --continue

If you get into trouble and want to back out and start all over again, just abort rebase.

git rebase --abort

When everything is resolved, push up your changes to remote.

git push origin work-branch

In some cases you might have to perform a force push, but be careful as this will overwrite changes on the remote branch.

Important: Never do a force push on the dev or master branch, only on your working branch.

git push origin -f work-branch

Deleting old working Branch

First, you will need to switch out of the branch you want to delete. Next make sure your changes are showing up in the dev or master branch. :-P

git checkout dev|master
git branch -d branch-name

Checking working Branch status

This will show you what branches exist locally and what branch you are on (denoted with a prefix of "*").

git branch

Example output:

  master
  raj-feat-cloud-function-training-data
  raj-feature-service-apis
  raj-function-sources
* raj-storage-cloud-function-prediction-object
  raj-storage-iam-roles

Switching to a Branch

git checkout <branch-name>

Advanced

You can squash all your commits into a single commit to clean up the history before pushing up your working branch.

Squash a working Branch

In the third step copy the Hash value obtained from step two.

git fetch -p origin
git merge-base <work-branch> origin/(dev|master)
git rebase -i <HASH>

In your text editor you will see something like:

pick 1fc6c95 chore: upgraded rxjs
pick 6b2481b chore: upgrade angular cli
pick dd1475d docs: new build notes
pick c619268 docs: fixed typos

Change "pick" to "squash" for every line except the first.

pick 1fc6c95 chore: upgraded rxjs
squash 6b2481b chore: upgrade angular cli
squash dd1475d docs: new build notes
squash c619268 docs: fixed typos

After saving and existing, you will be given a chance to enter a new commit message.

Before Squashing

After Squashing

After Rebasing & Fast-Forwarding

Save and close the file, in the new editor update the commit message then save and close it.

Complete the rebasing process, and push up your working branch for a pull-request.

git rebase origin/(dev|master)
git push origin <work-branch>
git checkout dev|master
git merge <work-branch> --ff

References

Conventional Commits
Auto generate changelog with Standard Version
Semantic Versioning
Merging vs. Rebasing
How to Rebase a Pull Request

rajinder-yadav/gitflow.md