Skip to content
saumon
gitktti
Public

About

The gitktti scripts are provided to help developers safely use git flow.

Resources

Readme
License
Activity

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository
BranchesTags

Repository files navigation

GitKtti™ Logo - Click to visit landing page

The gitktti project - by saumon™

Landing Page CPAN version License

The gitktti scripts are provided to help developers safely use git flow. So powerful... 🚀

saumon: Yes so powerful!

📋 Table of contents

📖 Description

Git flow is a branching methodology that organizes development around two main branches:

  • master : production branch containing only stable and tagged code
  • develop : development branch where all new features are integrated

Git flow principles

---
title: Git Flow - Overview
---
%%{init: { 'gitGraph': {'showCommitLabel': true, 'mainBranchName': 'master'}} }%%
gitGraph
    commit id: "v1.0.0"
    branch develop
    checkout develop
    commit id: "Init dev"

    branch feature/login
    checkout feature/login
    commit id: "Add login"
    commit id: "Fix login"

    checkout develop
    merge feature/login
    commit id: "Merge login"

    branch release/v1.1.0
    checkout release/v1.1.0
    commit id: "Prepare v1.1.0"

    checkout master
    merge release/v1.1.0
    commit id: "v1.1.0" tag: "v1.1.0"

    checkout develop
    merge release/v1.1.0

    checkout master
    branch hotfix/v1.1.1
    checkout hotfix/v1.1.1
    commit id: "Fix critical bug"

    checkout master
    merge hotfix/v1.1.1
    commit id: "v1.1.1" tag: "v1.1.1"

    checkout develop
    merge hotfix/v1.1.1
Loading

Branch types

  • feature/* : development of new features (branched from develop)
  • release/* : preparation of a new version (branched from develop)
  • hotfix/* : urgent fixes in production (branched from master)

🔎 Detailed workflows

Feature workflow

Feature branches are used to develop new functionality. They are created from develop and merged back into develop when complete.

---
title: Feature Workflow
---
%%{init: { 'gitGraph': {'showCommitLabel': true, 'mainBranchName': 'master'}} }%%
gitGraph
    commit id: "v1.0.0"
    branch develop
    checkout develop
    commit id: "Dev work"

    branch feature/new-login
    checkout feature/new-login
    commit id: "Add login form"
    commit id: "Add validation"
    commit id: "Fix styling"

    checkout develop
    commit id: "Other dev work"
    merge feature/new-login
    commit id: "Feature merged"

    checkout master
    merge develop
    commit id: "v1.1.0" tag: "v1.1.0"

    checkout develop
    commit id: "Continue dev"
Loading

Commands used:

# Create feature branch
kfeat -n feat/new-login
# or
kfix --mode feature --name new-login

# Finalize feature (merge to develop)
kfixend

Hotfix workflow

Hotfix branches are used for urgent production fixes. They branch from master and merge back to both master and develop.

---
title: Hotfix Workflow
---
%%{init: { 'gitGraph': {'showCommitLabel': true, 'mainBranchName': 'master'}} }%%
gitGraph
    commit id: "v1.0.0"
    branch develop
    checkout develop
    commit id: "Dev work"
    commit id: "More dev"

    checkout master
    branch hotfix/critical-bug
    checkout hotfix/critical-bug
    commit id: "Fix critical issue"
    commit id: "Add tests"

    checkout master
    merge hotfix/critical-bug
    commit id: "v1.0.1" tag: "v1.0.1"

    checkout develop
    merge hotfix/critical-bug
    commit id: "Hotfix in dev"

    checkout master
    merge develop
    commit id: "v1.1.0" tag: "v1.1.0"
Loading

Commands used:

# Create hotfix branch (from master)
kfix -n critical-bug
# or
kfix --name critical-bug

# Finalize hotfix (merge to master and develop, create tag)
kfixend

Release workflow

Release branches are used to prepare a new version. They branch from develop, allow for final adjustments, then merge to both master and develop.

---
title: Release Workflow
---
%%{init: { 'gitGraph': {'showCommitLabel': true, 'mainBranchName': 'master'}} }%%
gitGraph
    commit id: "v1.0.0"
    branch develop
    checkout develop
    commit id: "Feature A"
    commit id: "Feature B"
    commit id: "Feature C"

    branch release/v1.1.0
    checkout release/v1.1.0
    commit id: "Bump version"
    commit id: "Update changelog"
    commit id: "Fix minor issues"

    checkout master
    merge release/v1.1.0
    commit id: "v1.1.0" tag: "v1.1.0"

    checkout develop
    merge release/v1.1.0
    commit id: "Release merged"

    commit id: "New feature D"
Loading

Commands used:

# Create release branch (from develop)
kfix --mode release
# or
kreal
# This will propose version numbers based on last tag

# Finalize release (merge to master and develop, create tag)
kfixend

Hotfix during release workflow

Special case: when a release is in progress and a hotfix is needed, the hotfix must be merged into the release branch first.

---
title: Hotfix During Release
---
%%{init: { 'gitGraph': {'showCommitLabel': true, 'mainBranchName': 'master'}} }%%
gitGraph
    commit id: "v1.0.0"
    branch develop
    checkout develop
    commit id: "Features ready"

    branch release/v1.1.0
    checkout release/v1.1.0
    commit id: "Prepare release"

    checkout master
    branch hotfix/urgent-fix
    checkout hotfix/urgent-fix
    commit id: "Fix urgent bug"

    checkout release/v1.1.0
    merge hotfix/urgent-fix
    commit id: "Hotfix in release"

    checkout develop
    merge release/v1.1.0
    commit id: "Release + hotfix"

    checkout master
    merge release/v1.1.0
    commit id: "v1.1.0" tag: "v1.1.0"
Loading

Commands used:

# Create hotfix as usual
kfix

# When finalizing, the script will detect the release branch
# and automatically merge hotfix into release instead of develop
kfixend

📦 Installation

From CPAN (Recommended)

# Preferred method
cpanm App::GitKtti

# Alternative
cpan App::GitKtti

From Source

git clone https://github.com/saumon/gitktti.git
cd gitktti
./install.sh

Manual Installation

perl Makefile.PL
make
make test
make install

🗑️ Uninstallation

To properly uninstall GitKtti based on how it was installed:

git clone https://github.com/saumon/gitktti.git
cd gitktti
./uninstall.sh

The uninstall script will guide you through removing GitKtti cleanly:

  • Local installation: Simple directory removal guidance
  • System-wide: Automatic detection and removal of installed files
  • ~/perl5: Clean removal from local Perl library
  • CPAN: Uses cpan -U App::GitKtti or falls back to manual method

⚒️ Available Commands

After installation, the following commands are available:

  • gitktti-checkout - Switch between branches safely
  • gitktti-delete - Delete branches (local and remote)
  • gitktti-fix - Start a hotfix branch
  • gitktti-fixend - Finish a hotfix branch
  • gitktti-move - Rename branches
  • gitktti-tag - Create and push tags
  • gitktti-tests - Run diagnostic tests

Each command supports --help for detailed usage information.

🐰 Quick Start

# Run diagnostics
gitktti-tests

# Switch branches
gitktti-checkout --filter feature

# Start a hotfix
gitktti-fix --name critical-bug

# Create a tag
gitktti-tag --name v1.2.0

# Get help for any command
gitktti-checkout --help

⭐️ Recommended aliases

For users who prefer shorter commands, you can create these aliases:

alias kfeat='gitktti-fix --mode feature'
alias kreal='gitktti-fix --mode release'
alias kprune='gitktti-fix --prune'
alias kfix='gitktti-fix'
alias kfixend='gitktti-fixend'
alias ktag='gitktti-tag'
alias kco='gitktti-checkout'
alias kmove='gitktti-move'
alias kdel='gitktti-delete'
alias ktest='gitktti-tests'

Alias descriptions

Alias Purpose Description
kfeat Create feature branch Creates a new feature branch from develop. Equivalent to kfix --mode feature
kreal Create release branch Creates a new release branch from develop. Equivalent to kfix --mode release
kprune Clean local branches Deletes local branches that have been merged and are no longer needed
kfix Create hotfix/feature branch Creates a new branch (hotfix from master by default, or feature/release with --mode)
kfixend Finalize current branch Merges the current branch to appropriate target(s) and creates tags if needed
ktag Create/manage tags Creates or manages version tags on the repository
kco Smart checkout Intelligent branch checkout with Git flow awareness
kmove Rename branch Renames current branch locally and remotely
kdel Delete branch Deletes a local branch and its remote counterpart safely

Usage examples

With aliases (modern):

# Start working on a new feature
kfeat --name user-authentication # Creates feature/user-authentication

# Create a hotfix for production
kfix --name critical-security-fix # Creates hotfix/critical-security-fix from master

# Prepare a new release
kreal                           # Creates release/vX.Y.Z from develop

# Finish your work
kfixend                         # Merges current branch and handles Git flow

# Clean up merged branches
kprune                          # Removes local branches that are fully merged

# Create a tag manually
ktag                            # Creates and pushes tag

# Smart branch switching
kco                             # Switches to another branch

# Rename current branch
kmove --name feature/new-name   # Renames current branch locally and remotely
kmove                           # Interactive branch renaming

# Delete a branch
kdel --name feature/old-feature # Deletes specified branch locally and remotely
kdel --force                    # Force delete with interactive selection
kdel                            # Interactive branch deletion

# Run tests
ktest                           # Run diagnostic tests

Without aliases (full command names):

# Same functionality with full command names
gitktti-fix --mode feature --name user-authentication
gitktti-fix --name critical-security-fix
gitktti-fix --mode release
gitktti-fixend
gitktti-fix --prune
gitktti-tag
gitktti-checkout
gitktti-move --name feature/new-name
gitktti-delete --name feature/old-feature
gitktti-tests

🚀 CPAN Distribution Guide

This section is for maintainers who want to upload new versions of GitKtti to CPAN.

Prerequisites

  1. PAUSE Account: Create an account at https://pause.perl.org/pause/query?ACTION=request_id
  2. Quality Check: Ensure your code passes all tests and quality checks
# Run quality checks
perlcritic lib/App/GitKtti.pm
perl Makefile.PL
make test
make disttest

Command Line Upload

The recommended method for uploading to CPAN using the command line:

Step 1: Install Upload Tool

# Install CPAN::Uploader (preferred method)
cpanm CPAN::Uploader
# or
cpan CPAN::Uploader

Step 2: Configure PAUSE Credentials

# Create credentials file (one time setup)
echo "user YOUR_PAUSE_ID" > ~/.pause
echo "password YOUR_PASSWORD" >> ~/.pause
chmod 600 ~/.pause

Replace YOUR_PAUSE_ID and YOUR_PASSWORD with your actual PAUSE credentials.

Step 3: Prepare Distribution

# Clean and build distribution
make realclean
perl Makefile.PL
make
make test
make dist

This creates: App-GitKtti-X.Y.Z.tar.gz

Step 4: Upload to CPAN

# Upload your distribution
cpan-upload App-GitKtti-X.Y.Z.tar.gz

What Happens Next

  1. Immediate confirmation: Command line feedback
  2. PAUSE email: Confirmation email from PAUSE
  3. CPAN indexing: ~15-30 minutes to appear on CPAN
  4. MetaCPAN: Module visible on https://metacpan.org/

Complete Example

# Full workflow example
cd ~/work/scripts/perl/gitktti

# Quality checks
perlcritic lib/App/GitKtti.pm
make realclean
perl Makefile.PL
make test
make disttest

# Build distribution
make dist

# Upload (assuming credentials already configured)
cpan-upload App-GitKtti-2.0.0.tar.gz

Note: Only authorized maintainers with PAUSE access can upload to CPAN.

📋 Recent Releases

Release 2.0.4 - 05/03/2026

  • docs: README update (added link to landing page)
  • ktag: Supports both main and master branches for tagging

Release 2.0.3 - 28/02/2026

  • docs: GitHub logo on landing page

Release 2.0.2 - 22/02/2026

  • kfixend: GitHub dependabot branches compatibility

Release 2.0.1 - 01/02/2026

  • Lint fixes
  • kfixend: GitHub spec-kit feature branches compatibility

Release 2.0.0 - 10/09/2025

🚀 MAJOR MODERNIZATION RELEASE - CPAN READY!

  • BREAKING CHANGES: Complete architecture modernization for CPAN distribution
  • NEW: CPAN installable with cpanm App::GitKtti or cpan App::GitKtti
  • NEW: Scripts renamed with gitktti- prefix (e.g., gitktti-checkout)
  • NEW: Professional test suite and modern documentation
  • MIGRATION: Old perl gitktti_*.pl → New gitktti-* commands

Release 1.3.3 - 27/08/2025

  • GitKtti logo now displayed in terminal

Release 1.3.2 - 25/08/2025

  • Documentation reorganization

Release 1.3.1 - 24/08/2025

  • Added landing page

📚 For complete version history and detailed changelogs, see Changes file

About

The gitktti scripts are provided to help developers safely use git flow.

Resources

Readme
License
Activity

Stars

1 star

Watchers

1 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages