git workflow - GeoSmartCity-CIP/gsc-client GitHub Wiki

Download and install GIT

After installation, a few git settings must be configured correctly.

# This is very important!
git config --global push.default simple

# This is included in all your commits
git config --global user.name "Your Name"
git config --global user.email [email protected]

You can see all configs with git config --list

We have two main branches, 'master' and 'develop'.

'master' is the latest stable branch. It shall have tags with versions to make it possible to track which published versions have what source code. The average developer shall not interact with this branch at all.

'develop' is the active development branch. The average developer shall only create new branches based on the latest develop branch, when starting to work on a new feature. Changing the develop branch directly should not occur.

Other types of branches are feature branches, for common development work, release branches, for preparing releases to 'master' branch, and hotfix branches, for critical bugfixes that cannot go via the ordinary workflow.

The average developer should only interact with 'develop' and feature branches.

The ordinary workflow is as follows.

1. Create a feature branch on latest develop

• Push to remote/github to keep it visible for the others in your team
• Do your work on the feature branch (keep commits small, push after each commit)
• Rebase on top of develop if necessary (do not merge)
• Create pull request when feature is done
• Get review from someone
• Fix errors/issues
• Push updates
• Merge pull request (on Github.com)
• Delete branch

A task or work package is referred to as a "feature". It is common to prefix feature branches with feature/, so we'll try to follow that convention.

git checkout develop
git pull
git checkout -b feature/<feature-name>

This creates a new branch based on the latest develop branch.

git add <files>
git commit

Write a meaningful commit message. This will eventually end up in the master branch.

git push -u origin feature/<feature-name>

It is now available on Github. At this point, someone else can pull the branch and keep working on the feature (in case of sickness for example).

Further changes can be pushed directly.

git push

Note: After rebase (see below), Github will complain that your branch is "behind" the remote branch. This is a limitation in Github and should be ignored. Use git push --force to override this, do NOT call git pull after a rebase. However, do not use git push --force as a habit, it may overwrite some changes you didn't intend.

If develop branch changes and you need these changes in your feature branch, or there is a conflict that prevents a regular pull request (see below), you must rebase your branch onto the latest develop branch (DO NOT MERGE, IT BREAKS THE HISTORY).

On a clean branch (no uncommitted changes, see below how to stash temporary changes):

git checkout develop
git pull
git checkout feature/<feature-name>
git rebase develop

If conflicts, resolve the conflicts. With mergetool:

git mergetool
git rebase --continue

Manually:

(edit the text files)
git add <files>
git rebase --continue

If no conflicts, or after the conflicts are resolved, you are done and can run git push --force to update remote branch, which you should do immediately. The --force flag should be used sparingly, as it overrides any security checks (like if you changed the branch from a different computer, or someone else made an update for whatever reason).

Warning Set up your git settings properly first, to avoid overwriting multiple branches (including develop): git config --global push.default simple

git push --force origin <branch name>

Make sure remote branch is up to date with git push.

Go to the GeoSmartCity repo. On the top of the front page, it will list your recent branches with the option to compare and pull request. This will automatically set up the pull request to 'develop'. Write a meaningful title (this will occur in a commit message), some further details in the description (use @ mentions to ask for review) and see that the diff is as expected (doesn't contain others' commits or changes not part of the feature). When happy, hit 'Send pull request'.

Pull requests can be reviewed online or pulled locally to be tested and examined. The reviewer only needs to run:

git checkout feature/<feature-name>

Messages can be added inline in the pull request diff, or as comments in the pull request.

You cannot use git pull on someone else's branch after they have rebased (or changed their history). You should therefore not keep the local copy of the branch, so when done reviewing (and before checking out again):

git checkout develop
git pull
git branch -d feature/<feature-name>

This deletes the local copy of the branch. If you have made any changes for some reason, there will be a warning. Use capital -D flag to override (which means you lose any locally stored changes on that branch).

To replace a local copy of a branch with its remote counterpart without deleting the local version first use this sequence. YOU WILL LOSE ALL LOCAL CHANGES ON THAT BRANCH

# Make sure you are in the correct branch
git checkout feature/<feature-name>
# Fetch all remote branches (does not alter your local branches in any way)
git fetch --all
# Reset the currently checked out branch to the remote branch' state
# This will overwrite any local changes on the current branch.
git reset --hard origin/feature/<feature-name>

Since pull requests track a branch, any changes to the feature branch will be reflected in the pull request. When fixing stuff, commit as normal and run git push.

When done, hit the 'Merge'-button in Github. If this is not possible due to conflicts, the branch must be rebased locally onto the latest 'develop' branch (see above).

After a pull request is merged, the branch should be deleted (create new branches for each work package).

If you before a rebase have a dirty branch (some changes you don't want to commit), you can stash them.

git add .
git stash

NOTE Some versions of git does not require the first step, and just takes any uncommitted changes and stashes them. If so, it will suffice to do git stash to get a clean branch.

To recover these changes (can be done after a rebase, or on any other branch)

git stash pop

You can have multiple stashes. git stash pop always recovers the latest, and removes it from stash stack.

To list all stashes

git stash list

To recover a particular stash

git stash pop <stash name>