RFC: Gitflow and callbacks

[rwilcox]

It would be great to be able to write hook scripts, or callbacks, to be executed before and/or after git flow commits. Essentially: git hooks for git flow.

User stories for git flow callbacks:

• Auto increment a version number somewhere (somehow)
• time how long a feature took to implement
• check to see if current user is the release manager for project, and abort git flow release start if not
• Hotfix start should pull from origin before branching (hotfix start should pull from origin before branching #168)
• Add automatic push on git flow release finish (Release doesn't push tags by default #79)

How they could work:

• .git/hooks

  • post-(first command)-(second command). i.e.: post-feature-start
  • pre-(first command)-(second command). i.e.: pre-feature-start

  arguments: the arguments specified on the command line to git flow
  (git flow feature start login_screen would pass login screen)

  If a pre script returns non-0 exit code, git flow command aborts.

Alternatives to storing in .git/hooks:

.git/hooks is the standard place for holding git hooks. This has the advantage that it is standardized, and the disadvantage that this folder is not under version control. Although, if a team has defined standard git hooks before, they know how to handle this.

We could also define our own folder: .git_flow/hooks for this purpose. Which you could then store in version control and not have to deal with (copying files from version control into .git/hooks)

Prior Art

This has been discussed briefly in the community before (Git specific hooks: #60)

Some people that might be interested in this

Some people that might be interested in this (having used Git flow with them on projects in the past): @saturnflyer, @bokmann (Dave Bock, of the git flow screencast fame)

[johncongdon]

I really like the idea of the hooks. I was looking for something like that when I was trying to force the timings issue.

The biggest roadblock for me was going from feature back to develop, as there isn't a 'git flow' command to do this. I just use git checkout develop.

[jankeesvw]

This would be a great addition to git-flow!!

[petervanderdoes]

The main question to determine is where the hook script will be stored.
I do believe it's best to have a separate gitflow folder. This way the hooks will cloned when the repo is cloned.
The directory can be hardcoded or it can be added in the gitconfig, like gitflow.dir.hooks

My personal believe is to use the gitconfig solution with a default as .gitflow
The setup of the this would be as follows:
Questions asked during git flow init:
Where to store the gitflow configuration: default .gitflow
Where to store gitflow hooks: default hooks

This would create a directory structure:
.gitflow
.gitflow/hooks

I agree with the naming convention and how they could work.

[petervanderdoes]

Alright then,

I just published a fork of gitflow that implements hooks. I haven't written documentation yet, besides a bit in the code itself. What it comes down to is that for every command, there is a pre and post hook you can write.

Quick info

• You need to run git flow init after you install the update.
• Two new options are added to the init process:
  • gitflow configuration dir - defaults to .gitflow/
  • git flow hooks dir - defaults to hooks/
  • When changing the directory it needs to end in a directory separator, on *nix /
  • The full path of the hooks dir is configuration dir + hooks dir, so .gitflow/hooks/
• Hooks are to be named as suggested above except I choose for underscores instead of dashes
  pre_(first command)_(second command). i.e.: pre_feature_start
• You can also write hooks for the default commands
• The hook should be named pre_(first command)_default, so if you want a hook on git flow feature the hook name should be pre_feature_default
• Hooks are to be executable
• Hooks should always have exit code zero on success, other exit code will stop the git flow process.

You can find the feature branch here: https://github.com/petervanderdoes/gitflow/tree/feature/implent_hooks

So I would say test away, this is an active coding branch so thing might break every now and then.

Issues

If you find any issues please submit them here: https://github.com/petervanderdoes/gitflow/issues

[jankeesvw]

I think .gitflow is the best option, it would be great if you could put these scripts in the repository!

How can I test this branch, and reinstall the original Git Flow afterwards?

[petervanderdoes]

Steps

• Clone my repo in a separate directory from the original gitflow repo
• git flow init -d (I used the default settings)
• git flow feature checkout implent_hooks
• Copy the files to the working directory of gitflow, in my case /usr/local/bin
• Go to your project's git repository
• git flow init

and that's it. You can write your own hooks as described above.

To return to the original gitflow files:

• Goto your original gitflow repo
• Checkout master
• Copy the files to the working directory of gitflow, in my case /usr/local/bin

To return your project's git repo to pristine state

• Go to project's repo root directory
• rm -rf .gitflow
• git config unset gitflow.dir.main
• git config unset gitflow.dir.hooks

[petervanderdoes]

I'll be rewriting this based on another patch I wrote, #184 Feature/separate gitflow config directory and file

That patch does not let you set your own main dir, it's hardcoded, basically like git itself.

[bobthecow]

i'd prefer it to be hardcoded, personally.

[petervanderdoes]

As the #184 is hard coded nothing will change in that matter. Besides the proposed action scripts, I'm thinking about adding filter scripts as well.

Example of a filter script
Dynamically change the tag during a git flow release finish.
A filter hook would be called after the code has set the tag e.x. voptimus_prime (version prefix has been set to v)
The script gets that tag and converts it to the standard of the project, for example vOptimusPrime and sends it back to the git flow process.

Another example could be that the project needs to have a current date prefix:
The script receives voptimus_prime, changes the tag to 20111231-optimus_prime and again sends this tag back to git flow.

[nvie]

OK, I've read a lot of the discussion here and took a look at some of the patches that are proposed. I definitely see a justification for the "hooks" feature, but I'd like it to be intuitive, adhere to existing standards and be simple even without documentation.

This is very close, if not identical, to @rwilcox's proposal.

Let me elaborate on how I'd like it:

• Intuitive: the git-flow hooks should blend in with regular git hooks. Yes, there won't be a direct way of storing the scripts under version control, but there exists no such way with normal Git either. There are simple tricks to do it anyway, though.
• Standardised: I don't see the need in being able to specify the directory. It complicates git-flow's init process without significant benefit.
• Simplicity: it should be there when you need it, but you needn't care if you don't know about it or are not interested in using them.

So what about this proposal?

• git-flow init won't be changed.
• Naming convention for the hook scripts follows the Git hooks conventions:
  .git/hooks/{pre,post}-{subcmd}
• For example:
  .git/hooks/pre-flow-feature-start
.git/hooks/post-flow-release-finish
• For each subcommand, the appropriate hook scripts will be called as you'd intuitively expect. If no such script exists, that's fine, of course.
• The pre script will get called with arguments that "make sense" for the call at hand.
• Returning from the pre script with a non-zero exit code will terminate the action.
• The post script will only be called when the action was successful (or when it makes sense to explicitly communicate the failure—although I cannot think of a good example at the moment).

An exhaustive list of 26 useful hook scripts:

• {pre,post}-flow-{feature,release,hotfix}-start
• {pre,post}-flow-{feature,release,hotfix}-finish
• {pre,post}-flow-{feature,release,hotfix}-publish
• {pre,post}-flow-{feature,release,hotfix}-track
• {pre,post}-flow-feature-pull

[petervanderdoes]

I renamed the feature/implent_hooks to feature/implement-hooks (the typo was driving me nuts :) ) and made changes reflecting nvie's proposal.

Features not implemented yet are the calling of the hooks with parameters and currently a hook can be called for every command available. Opening a pull request in a second.

[johncongdon]

Is there a git flow command that takes you back to the develop branch, other than git checkout develop?
This was a hook will be called for that stage as well.

[petervanderdoes]

I believe I implemented all hooks as described.
If somebody can take a look, I appreciate that. See pull request #185

[neersighted]

+1

[azu]

+1

[rbt]

Really looking forward to this so I can get proper bug system integration.

feature finish will automatically mark commits tagged with 'Ticket #123' as Resolved.

release start will plug the version number into the bug system and allow tickets to be filed against that release
release start will also mark all tickets involved in the release as being for this release, just in-case some person forgot one.

This will greatly help developers, QA, and support staff figure out which pieces of functionality are being impacted at any given time.

[ernoaapa]

+1

[petervanderdoes]

The hooks are implemented in my fork, on the develop branch. https://github.com/petervanderdoes/gitflow

[ernoaapa]

Thanks! Have to test that one. I think this is so great feature that this should be added to gitflow.

[gbirke]

+1

[evanstern]

+1 PLEASE!

[calumbrodie]

+1

[cobhimself]

+1

[mgaitan]

+1

[88Alex]

+2 ;-)

[aptituz]

Is there any progress with that? We really have a need for hooks in git-flow to ease things and would like to avoid working with a fork.

Apart from that, I have some comments in regard to the configurability of the hookdir. As @nvie stated, he'd prefer to use a fixed location for the hook dir (path by convention). I think, a configurable path as it used to be in the previous patch of @petervanderdoes would be way better, since:

1. Its consistent with other settings of gitflow like the branch settings

2. It allows to configure a global hookdir (e.g. for package-distributed hooks)

3. It uses a well defined interface for the setting (git config)

Please reconsider re-adding support and merging it.

[petervanderdoes]

I know you say you don't want to work with a fork but this has been open for 2 years now. I highly doubt it will be implemented here.

Besides the configurable hook dir, this is implemented in my fork git-flow (AVH Edition)
My fork has diverged to much to make this into an easy pull request for nvie's gitflow,

Checkout the changelog for more information about bugfixes and new features implemented in my fork.

[dongli]

Why this feature is still not available in gitflow after two years?

[petervanderdoes]

It seems the project is no longer maintained.

[cobhimself]

@petervanderdoes, it appears so. Any issues found when moving to your fork? If this repo isn't going to be maintained, I'll move over to yours; I just want to make sure I don't create issues on my end by moving. =D

[petervanderdoes]

Non that I heard of.

[jhirbour]

Is this ever going to be merged? It was be really nice for our workflow if we could hook into git-flow . We've build some code that makes cards in pivotal.