Skip to content

Twgit EN

Jump to bottom Edit New page
fbndsprz edited this page Oct 24, 2016 · 5 revisions

[ Home ][ Workflow ][ Workflow EN ][ Twgit ][ Twgit EN ]

Table of Content

1. Introduction
2. Install
    2.1. twgit Install
    2.2. Auto-update
    2.3. Transition
3. Help
    3.1. Contextual Help
    3.2. Syntax Highlighting
    3.3. Auto-completion
    3.4. Logs
4. List branchs
    4.1. List features
    4.2. List releases
    4.3. List tags
    4.4. List hotfixes
5. Create a branch
    5.1. Create a feature
    5.2. Create a hotfix
    5.3. Create a release
6. Merge/remove a branch
    6.1. Merge a feature in a realease
    6.2. Merge/remove a hotfix
    6.3. Merge/remove a release
7. Remove a branch
    7.1. Remove a feature
    7.2. Remove a hotfix
    7.3. Remove a release
8. Examples
    8.1. Working on a feature
    8.2. A tag is preventing to close a release
    8.3. Merge a feature in a realease

1. Introduction

To simplify to the maximum usage of git workflow, a new tool named twgit (Twenga git) was developed on an architecture similar to that of git-flow. The source code is available under [Creative Commons Attribution-NonCommercial-ShareAlike 3.0](http://creativecommons.org/licenses /by-nc-sa/3.0/) license and hosted on Github: https://github.com/Twenga/twgit.

Its main features allow to:

  • Reduce the number of git commands,
  • automate associated checks
  • Easily get usefull information: what features are in the release, should a feature get the latest tags, who are the main contributors to a feature...

It helps in the management of local and remote branches in the new workflow. When it creates, merges or deletes a branch, it always does in both local and remote repositories. This behavior does not affect the commits and at any time you can still run a "native" Git command for a more limited action. To lift ambiguities and ease team work on the same project, displayed information are always based on the remote branches.

Branch names are constrained depending on their type:

  • features are named feature-<name>,
  • hotfixes are named hotfix-<version>,
  • releases are named release-<name|version>,
  • tags are named v<version>.

Where <name> is a free text string without space, and <version> is by default an application version number such as major.minor.revision : hotfixes increment the "revision" number and releases increment "major" ou "minor" numbers (depending on the functional scope or backward-compatibilty changes for instance).

Whenever a twgit command requires a branch name, it must be entered without its prefix.

2. Installation

2.1. twgit Install

Prerequisites:

  • bash v4 minimum (2009),
  • git v1.7.2 minimum (2010).

In the directory of your choice, for example ~/twgit:

git clone [email protected]:Twenga/twgit.git .
sudo make install

If not already the case, the Makefile will allow you to customize your Bash prompt to display Git information when browsing your repository folders. See for instance FR - Des informations Git dans son prompt or EN - Add git branch name to bash prompt.

Troubleshooting :

  • If you get a "-bash: git: command not found" during the git clone, then you need first to install the git client in your environment. For instance, on Ubuntu : sudo apt-get install git.
  • If you are asked for a password you don't have (the one of the git user), it means you have to generate/add your SSH key to Github : Account Settings.
  • If you get a "-bash: make: command not found" during make install, then you need to install the make command, that can be found in the "build-essential" package.

2.2. Auto-update

Twgit features a half-automated update mechanism. This is all the more interesting that the tool is young...

Every "N" days (parameter in the config file) and if the ".git" folder of twgit installation directory has not been deleted, then twgit searches for an updated version when any command is executed.

If the installed version is the latest available, a simple message is displayed stating that the next check will occur in "N" days:

If not, twgit prompts the user for update:

2.3. Transition

Here is how to transition from your current git setup to the new workflow:

  • To create the "stable" branch from "master" and create the tag:
git checkout --track -b stable master
git push --set-upstream origin stable
git tag -a v4.11.0 -m 'premier tag'
git push --tags origin
  • For each development branch that is still opened and that you wish to migrate to the new system:
twgit feature migrate <oldfeaturefullname> <newfeaturename>

For instance : "twgit feature migrate rm7880 7880"

This call executes pretty much the following commands:

git checkout --track -b feature-[new_name] origin/[old_name]
git push --set-upstream origin feature-[new_name]
git branch -D [old_name]
git push origin :[old_name]
git merge --no-ff stable

3. Help

3.1. Contextual Help

The same way as git, twgit offers a contextual help at each level. Main help:

Help for "release" command:

3.2. Syntax Highlighting

A consistent Syntax Highlighting exists at application level that allows to quickly identify:

  • a blocking error:
  • a warning:
  • a question:
  • a section title:
  • a subtitle:
  • a Redmine information:
  • an information:
  • an internal check:
  • a git command executed by twgit:

3.3. Auto-completion

Auto-complete (hitting twice the "tab" key) is available at each level (command, action, references):

3.4. Logs

Twgit logs any activity in 2 files:

  • application errors in $TWGIT_HISTORY_ERROR_PATH, set by default to $TWGIT_ROOT_DIR/.history.error,
  • everything else in $TWGIT_HISTORY_LOG_PATH, set by default to $TWGIT_ROOT_DIR/.history.log.

4. List branchs

4.1. List features

twgit feature list lists the current features, with the subject of the associated Redmine ticket, and the following categorization:

  • the features whose development has stopped and that have been delivered/merged into the current release;
  • the features merged into the current release but whose development continues (twgit prevents finishing the release while such branches exist);
  • the features without any relation with a release.

If twgit detects fetaures merged into the stable branch, then they will be listed with a warning : they are indeed not supposed to even exist. When finishing a release, all associated features are removed.

Added to that twgit will list with a warning:

  • every branch out of nomenclature,
  • every branch not having the last tags (and whose development continues, a priori).

You can get a more compact display with the -c option:

4.2. List releases

twgit release list lists the current release. Only one release is allowed at a time (twgit will enforce this rule and display a warning if needed). And as qualified releases are merged to stable then removed, listing the releases is limited to displaying the current release, if any.

If a release exists, the associated features will be listed:

  • as merged for those whose development has stopped when merged into the release,
  • as merged, then in progress for the features whose development has started again (twgit will prevent finishing the release while such branchesexist),
  • in any case, the subject of the associated Redmine, if found.

Same as for the features, every branch not integrating the latest tags will be displayed with a warning describing the problem.

Algorithm:

Determining the link between a feature and the current release is quite complex. It needs first to compute a few nodes:

  • "release/feature merge base" is the node that would be selected as the best common ancestor for a merge between the release and the feature
  • "(rel/feat)/stable merge base" is the node that would be selected as the best common ancestor for a merge between the preceding nodeand the stable branch
  • "dependency merge" is the immediate child of "release/feature merge base" node, of type merge and not belonging to the release ancestors

Then:

  • if "release/feature merge base" is identical to the feature "HEAD", then the feature has the type merged
  • else if "release/feature merge base" differs from "(rel/feat)/stable merge base" and we cannot find the "dependency merge" node, then the feature has the type merged, then in progress
  • else feature has the type free

Hence, if the feature a is merged into the feature b and if b is pushed into the release, then this dependency link between features means that a will be considered as pushed into the release.

4.3. List tags

twgit tag list lists les 5 last tags.

4.4. List hotfixes

Only one hotfix is allowed at a time (twgit will enforce this rule and display a warning if needed). And as qualified hotfixes are merged to stable then removed, listing the releases is limited to displaying the current hotfix, if any.

5. Create a branch

5.1. Create a feature

twgit feature start allows:

  • to create a new feature, both on the local and remote repositories, starting from the last tag,
  • or to branch on an existing remote feature,
  • or to checkout a feature existing both locally and on the remote repository.

The feature "name" should be ether an Redmine ticket number (child or parent), for instance 4556, or the name of a sub-project as appearing in Redmine URL, for instance payment-terms for the sub-project Billing Conditions - Payment Card.

Algorithm:

  • check that the name is valid
  • detect if the local branch exists
  • if the local branch exists:
    • perform a checkout
  • else:
    • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
    • update the remote references (including remove branches)
    • detect if the remote branch exists
    • if the remote branch exists:
      • perform a checkout and activate tracking (which allows simple git push and git pull without argument)
    • else (it's a creation):
      • check that at least 1 tag exists on the stable branch and get the latest
      • create the local branch from this tag
      • execute a technical commit (blank) with a preformated comment
      • create the associated remote branch and activate tracking (which allows simple git push and git pull without argument)
  • in any case notify if tags are not present in the feature

5.2. Create a hotfix

twgit hotfix start allows:

  • to create a new hotfix, both on the local and remote repositories, starting from the last tag,
  • or to branch on an existing remote hotfix,
  • or to checkout a hotfix existing both locally and on the remote repository.

If the tag version is major.minor.revision, then the hotfix version will be major.minor.(revision+1).

Algorithm:

  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • update the remote references (including remove branches)
  • detect if the remote hotfix exists (there can be only one !)
  • if it's a new hotfix:
    • check that at least 1 tag exists on the stable branch,
    • get the latest tag, then increment its revision number to build the new hotfix name
    • create the local branch with this name from the latest tag
    • execute a technical commit (blank) with a preformated comment
    • create the associated remote branch and activate tracking (which allows simple git push and git pull without argument)
  • else:
    • check that the name is valid
    • detect if the local branch exists
    • if the local branch exists:
      • perform a checkout
    • else:
      • checkout the remote branch and activate tracking (which allows simple git push and git pull without argument)

5.3. Create a release

twgit release start allows:

  • to create a new release, both on the local and remote repositories, starting from the last tag,
  • or to branch on an existing remote release,
  • or to checkout a release existing both locally and on the remote repository.

By default, if the tag version is major.minor.revision, then the release version will be major.(minor+1).revision. You can increment the major version with the -M option. You can also give the release any name of your choosing.

Algorithm:

  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • update the remote references (including remove branches)
  • check that at least 1 tag exists on the stable branch,
  • detect if the remote release exists (there can be only one !)
  • if no release name was provided:
    • if a release already exists, then do as if the name was given
    • else:
      • get the latest tag, then increment its minor or major number (depending on the option) to build the new release name récupère
      • ask for confirmation
  • check that the name is valid
  • if a release already exists:
    • check that the name given to the release is the same as the current release
    • detect if the local branch exists
    • if the local branch exists:
      • perform a checkout
    • else:
      • checkout the remote branch and activate tracking (which allows simple git push and git pull without argument)
  • else:
    • create the local branch with the chosen name from the latest tag
    • execute a technical commit (blank) with a preformated comment
    • create the associated remote branch and activate tracking (which allows simple git push and git pull without argument)
  • in any case notify if tags are not present in the feature

You can reset the current release using twgit release reset. This command removes the releases, before creating it again, without any feature.

6. Merge/remove a branch

6.1. Merge a feature in a realease

twgit feature merge-into-release <featurename> allows to merge a feature into the current release.

Algorithm:

  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • update the remote references (including remove branches)
  • detect if the remote release exists (there can be only one !)
  • ensure that the feature exists on the remote repository
  • try and execute the following commands sequentially:
twgit feature start $feature
git pull $TWGIT_ORIGIN $feature_fullname
twgit release start
git pull $TWGIT_ORIGIN $release_fullname
git merge –no-ff $feature_fullname
git push $TWGIT_ORIGIN $release_fullname
  • in case of error, stop the workflow and warn user about failed commands

6.2. Merge/remove a hotfix

twgit hotfix finish allows to close the current hotfix, while merging it into the stable branch and creating the associated tag. The hotfix branch is removed at the end of the process.

Algorithm:

  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • update the remote references (including remove branches)
  • ensure a hotfix is ongoing and get its name
  • if a local branch exists for this hotfix, ensure it is NOT older than the remote (not a problem if it is younger)
  • build a tag name using the hotfix name and check it is valid
  • check that this tag name is not already used
  • checkout local stable branch
  • merge remote stable branch into local stable
  • merge local hotfix branch into local stable branch
  • create the tag on the stable branch
  • push the tag into the remote repository
  • remove the hotfix (cf. twgit hotfix remove)
  • if a release is ongoing, warn the user not to forget merging the new tag into the release before trying to finish it (anyway twgit will prevent that from happening)

6.3. Merge/remove a release

twgit release finish allows to close the current release, while merging it into the stable branch and creating the associated tag. The release branch is removed at the end of the process, together with all the branches of the associated features.

Algorithm:

  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • update the remote references (including remove branches)
  • ensure a release is ongoing and get its name
  • build a tag name using the release name or the optional parameter and check it is valid
  • check that this tag name is not already used
  • ensure there is no ongoing hotfix
  • if tags have been created since the release start, ensure they are merged into the release
  • ensure no feature merged into has ongoing development
  • if a local branch exists for this release, and if the local is older than the remote branch:
    • if the local is a direct ancestor, then prompt to perform a 'pull'
    • else, stop the process
  • checkout local stable branch
  • merge remote stable branch into local stable
  • merge local release branch into local stable branch
  • create the tag on the stable branch
  • push the tag into the remote repository
  • remove all associated features (cf. twgit feature remove)
  • remove the release (cf. twgit release remove)

7. Remove a branch

To mitigate the risk of error when removing a branch:

  • auto-completion has been disabled on this action
  • providing the branch name is mandatory even if it could be computed in case of hotfix or release.

7.1. Remove a feature

twgit feature remove allows to remove the given feature, together on the local and remote repository.

Algorithm:

  • check that the name is valid
  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • if the working tree (the current branch) is on the branch being removed, checkout the stable branch
  • update the remote references (including remove branches)
  • remove the local branch
  • remove the remote branch

7.2. Remove a hotfix

twgit hotfix remove allows to remove the given hotfix, together on the local and remote repository.

Algorithm:

  • check that the name is valid
  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • if the working tree (the current branch) is on the branch being removed, checkout the stable branch
  • update the remote references (including remove branches)
  • remove the local branch
  • remove the remote branch

7.3. Remove a release

twgit release remove allows to remove the given release, together on the local and remote repository.

Algorithm:

  • check that the name is valid
  • ensure that the working tree (the current branch) is in status "nothing to commit (working directory clean)"
  • if the working tree (the current branch) is on the branch being removed, checkout the stable branch
  • update the remote references (including remove branches)
  • remove the local branch
  • remove the remote branch

8. Examples

TODO give more examples...

8.1. Working on a feature

Be it new or not, local or remote, start your feature with:

twgit feature start [feature_name] # for instance, a Redmine ticket

Work on your feature the commit:

git add [path]
git commit -am '[msg]'
git push

8.2. A tag is preventing to close a release

If you get this kind of error message when running the command twgit release finish:

/!\\ You must merge following tag(s) into this release before close it: v1.1.7, v1.1.8

Then:

git checkout release-1.2.6 # or if the release doesn't exist locally: twgit release start 1.2.6
git pull
git merge --no-ff v1.1.8
git push

8.3. Merge a feature in a realease

Twgit now allows to automate this step using: twgit feature merge-into-release xxxx cf. Merge/remove a branch

If you still want to do it manually:

If you don't have the feature locally:

twgit feature start 7990

Merge it into the release:

git checkout release-1.2.6 # or twgit release start
git pull
git merge --no-ff feature-7990
git push
Add a custom footer
Add a custom sidebar
Clone this wiki locally