format-commit 1.0.1 → 1.1.0

package/README.md

@@ -52,37 +52,51 @@ format-commit --config
 
 All configuration is stored in the `commit-config.json` file. Here is the list of all options.
 
-`format`
+**`format`**
 
 Commit title format:
-- 1: `(type) Name` / 2: `(type) name`
-- 3: `type: Name` / 4: `type: name`
-- 5: `type(scope) Name` / 6: `type(scope) name`
-- 7: `type(scope): Name` / 8: `type(scope): name`
+- 1: `(type) Description` / 2: `(type) description`
+- 3: `type: Description` / 4: `type: description`
+- 5: `type(scope) Description` / 6: `type(scope) description`
+- 7: `type(scope): Description` / 8: `type(scope): description`
+- "custom"
 
-`branchFormat`
+**`customFormat`**
+
+Custom commit format pattern. Uses keywords `type`, `scope`, `description` and custom field(s) with `{field}` placeholders. Keywords are case-sensitive.
+
+Example: `{Issue ID} - type - scope - Description`.
+
+**`branchFormat`**
 
 Branch naming format:
 - 1: `type/description`
 - 2: `type/scope/description`
+- "custom"
+
+**`customBranchFormat`**
+
+Custom branch format pattern. Uses keywords `type`, `scope`, `description` and custom fields with `{field}` placeholders. Keywords are case-sensitive. Separators must be valid in Git branch names (no spaces, `~`, `^`, `:`, `?`, `*`, `[`, `\`, `..` or `//`). Dynamic parts (description, custom fields) are automatically sanitized to be branch-safe.
+
+Example: `type/{Issue ID}-Description`.
 
-`types`
+**`types`**
 
 Allowed commit and branch types (default: `feat`, `fix`, `core`, `test`, `config`, `doc`)
 
-`scopes`
+**`scopes`**
 
-Scopes for commit and branch categorization (used in formats 5-8 for commits, format 2 for branches)
+Scopes for commit and branch categorization (used in formats 5-8 for commits, format 2 for branches, or when a custom format includes the `scope` keyword)
 
-`minLength`
+**`minLength`**
 
 Minimum length required for the commit title.
 
-`maxLength`
+**`maxLength`**
 
 Maximum length required for the commit title and branch description.
 
-`changeVersion`
+**`changeVersion`**
 
 Version change policy:
 - `never (ignore)`: Never change version, skip prompt (default)
@@ -90,44 +104,44 @@ Version change policy:
 - `only on release branch`: Only release branch commits require version change
 - `always`: All commits require version change
 
-`releaseBranch`
+**`releaseBranch`**
 
 Main/release branch name (used if changeVersion = `only on release branch`)
 
-`showAllVersionTypes`
+**`showAllVersionTypes`**
 
 Show all version types or only main ones (`major`/`minor`/`patch`/`custom`)
 
-`ai.enabled`
+**`ai.enabled`**
 
 Enable AI commit title suggestions (default: `false`)
 
-`ai.provider`
+**`ai.provider`**
 
 AI provider:
 - `anthropic` (Claude)
 - `openai` (GPT)
 - `google` (Gemini)
 
-`ai.model`
+**`ai.model`**
 
 Model identifier (e.g., `claude-haiku-4-5` or `gpt-4o-mini`)
 
-`ai.envPath`
+**`ai.envPath`**
 
 Path to .env file containing the AI provider API key (e.g., `.env`)
 
-`ai.envKeyName`
+**`ai.envKeyName`**
 
 Name of the environment variable for the API key (e.g., `OPENAI_API_KEY`)
 
-`ai.largeDiffTokenThreshold`
+**`ai.largeDiffTokenThreshold`**
 
 Number of tokens from which not to use AI automatically.
 
 ### AI Suggestions
 
-When AI is enabled, your staged changes will be processed by the defined AI to suggest commit titles that:
+When AI is enabled, your staged changes will be processed by the defined model to suggest commit titles that:
 - Follow your configured format and naming conventions
 - Automatically select appropriate types and scopes
 - Respect your min/max length constraints
@@ -145,7 +159,8 @@ You can either:
 | :---- | :--- | :---------- |
 | `-c` | `--config` | Generate or update configuration file |
 | `-b` | `--branch` | Create a new standardized branch |
-| `-t` | `--test` | Test mode - preview without executing Git commands |
+| `-t` | `--test` | Preview without executing Git commands |
+| `-d` | `--debug` | Display additional logs |
 
 ## Contributing
 

package/lib/ai-service.js

@@ -30,49 +30,48 @@ const getOptimizedGitDiff = () => {
 };
 
 /** Build AI prompt */
-const buildPrompt = (diffData, config) => {
+const buildPrompt = (diffData, config, customFieldValues = {}) => {
   const typesList = config.types.map(t => t.value).join(', ');
-  const types = config.types.map(t => `${t.value} (${t.description})`).join(', ');
+  const types = config.types.map(t => `${t.value} is for ${t.description}`).join('\n   > ');
   const scopesList = config.scopes ? config.scopes.map(s => s.value).join(', ') : null;
   const scopes = config.scopes
-    ? config.scopes.map(s => `${s.value} (${s.description})`).join(', ')
+    ? config.scopes.map(s => `${s.value} is for ${s.description}`).join('\n   > ')
     : null;
 
-  let formatInstruction = '';
-  switch (config.format) {
-    case 1:
-      formatInstruction = 'Format: (type) Title with first letter capitalized';
-      break;
-    case 2:
-      formatInstruction = 'Format: (type) title in lowercase';
-      break;
-    case 3:
-      formatInstruction = 'Format: type: Title with first letter capitalized';
-      break;
-    case 4:
-      formatInstruction = 'Format: type: title in lowercase';
-      break;
-    case 5:
-      formatInstruction = 'Format: type(scope) Title with first letter capitalized';
-      break;
-    case 6:
-      formatInstruction = 'Format: type(scope) title in lowercase';
-      break;
-    case 7:
-      formatInstruction = 'Format: type(scope): Title with first letter capitalized';
-      break;
-    case 8:
-      formatInstruction = 'Format: type(scope): title in lowercase';
-      break;
-  }
-
   const exampleTitle = utils.formatCommitTitle(
     config.types[0].value,
-    'example change description',
+    'Description of changes',
     config.format,
-    config.scopes?.[0]?.value
+    config.scopes?.[0]?.value,
+    config.customFormat,
+    customFieldValues
   );
 
+  const formatHasScope = config.format === 'custom'
+    ? utils.customFormatHasScope(config.customFormat)
+    : config.format >= 5;
+
+  const changeable = formatHasScope ? 'type, scope and description' : 'type and description';
+  const scopeInstruction = formatHasScope ? `\n- ONLY use these scopes (do not invent one outside this list): ${scopesList}
+- Scope descriptions, to figure out which one to choose:\n   > ${scopes}` : '';
+
+  let template;
+  if (config.format === 'custom' && config.customFormat) {
+    const segments = utils.parseCustomFormat(config.customFormat);
+    template = segments.map(seg => {
+      if (seg.type === 'literal') { return seg.value; }
+      if (seg.type === 'field') { return customFieldValues[seg.label] || `{${seg.label}}`; }
+      if (seg.type === 'keyword') { return `<${seg.keyword}>`; }
+      return '';
+    }).join('');
+  } else {
+    template = utils.formatCommitTitle('<type>', '<description>', config.format, formatHasScope ? '<scope>' : undefined);
+  }
+
+  const formatInstruction = `- Format pattern: "${template}"
+- Example: "${exampleTitle}"
+- ONLY replace ${changeable} placeholders, keep everything else exactly as shown`;
+
   return `You must analyze git changes and return ONLY a valid JSON array. NO explanations, NO markdown, NO additional text.
 
 Git diff stats:
@@ -82,16 +81,16 @@ Git diff:
 ${diffData.diff}
 
 STRICT REQUIREMENTS:
-- ${formatInstruction}
-- Example format: "${exampleTitle}"
-- ONLY use these types (NO others): ${typesList}
-- Type descriptions: ${types}
-${scopes ? `- ONLY use these scopes (NO others): ${scopesList}\n- Scope descriptions: ${scopes}` : '- No scopes - DO NOT include scope in output'}
+${formatInstruction}
+- ONLY use these types (do not invent one outside this list): ${typesList}
+- Type descriptions, to figure out which one to choose:\n   > ${types}${scopeInstruction}
 - Length: ${config.minLength}-${config.maxLength} chars per title
 - Return exactly 4 different commit titles
-- Output MUST be a raw JSON array with NO text before or after
+- Output MUST be a raw JSON array
+
+If changes seem to concern very different things, suggest at least one title that attempts to be exhaustive on the most important points, using commas and/or "&". Avoid generic titles such as "Bug fixes and improvements".
 
-YOUR RESPONSE MUST BE EXACTLY THIS FORMAT (no other text):
+YOUR RESPONSE MUST BE EXACTLY THIS FORMAT (no other text before or after):
 ["title 1", "title 2", "title 3", "title 4"]`;
 };
 
@@ -185,9 +184,10 @@ const callGeminiAPI = async (prompt, apiKey, model) => {
   return data.candidates[0].content.parts[0].text;
 };
 
+
 /** Validate and normalize AI suggestion */
-const validateAndNormalizeSuggestion = (suggestion, config) => {
-  const result = utils.parseAndNormalizeCommitTitle(suggestion, config);
+const validateAndNormalizeSuggestion = (suggestion, config, customFieldValues = {}) => {
+  const result = utils.parseAndNormalizeCommitTitle(suggestion, config, customFieldValues);
 
   // Returns null if invalid format/type/scope/length
   if (result.error) {
@@ -203,7 +203,7 @@ const validateAndNormalizeSuggestion = (suggestion, config) => {
 };
 
 /** Generate commit title suggestions using AI */
-const generateCommitSuggestions = async (config, testMode) => {
+const generateCommitSuggestions = async (config, debugMode, customFieldValues = {}) => {
   const diffData = getOptimizedGitDiff();
   if (!diffData) {
     return [];
@@ -214,10 +214,14 @@ const generateCommitSuggestions = async (config, testMode) => {
     throw new Error('AI API key not found in .env');
   }
 
-  const prompt = buildPrompt(diffData, config);
+  const prompt = buildPrompt(diffData, config, customFieldValues);
   const estimatedTokens = Math.ceil(prompt.length / 4);
   const threshold = config.ai.largeDiffTokenThreshold || 20000;
 
+  if (debugMode) {
+    utils.log('<`git diff`>\n\n' + prompt.slice(prompt.indexOf('STRICT REQUIREMENTS:')), 'debug');
+  }
+
   if (estimatedTokens > threshold) {
     const { confirm } = await prompts({
       type: 'confirm',
@@ -243,8 +247,8 @@ const generateCommitSuggestions = async (config, testMode) => {
 
   const jsonMatch = responseText.match(/\[[\s\S]*\]/);
   if (!jsonMatch) {
-    if (testMode) {
-      utils.log(responseText, 'warning');
+    if (debugMode) {
+      utils.log(responseText, 'debug');
     }
     throw new Error('No JSON array found in AI response');
   }
@@ -252,8 +256,8 @@ const generateCommitSuggestions = async (config, testMode) => {
   const suggestions = JSON.parse(jsonMatch[0]);
 
   if (!Array.isArray(suggestions) || !suggestions.length) {
-    if (testMode) {
-      utils.log(responseText, 'warning');
+    if (debugMode) {
+      utils.log(responseText, 'debug');
     }
     throw new Error('Invalid AI response format');
   }
@@ -261,14 +265,14 @@ const generateCommitSuggestions = async (config, testMode) => {
   // Validate and normalize each suggestion
   const validationResults = suggestions.map(s => ({
     original: s,
-    normalized: validateAndNormalizeSuggestion(s, config)
+    normalized: validateAndNormalizeSuggestion(s, config, customFieldValues)
   }));
 
   // Log rejected suggestions in test mode
-  if (testMode) {
+  if (debugMode) {
     validationResults.forEach(({ original, normalized }) => {
       if (normalized === null) {
-        utils.log(`rejected: "${original}"`, 'warning');
+        utils.log(`rejected: "${original}"`, 'debug');
       }
     });
   }

package/lib/commit.js

@@ -24,7 +24,7 @@ const promptWithPrefill = (message, prefill, validate) => {
         output: process.stdout
       });
 
-      const questionText = `${kleur.bold(message)}\n› `;
+      const questionText = `${kleur.bold(message)}\n> `;
 
       // Handle Ctrl+C to cancel
       rl.on('SIGINT', () => {
@@ -102,7 +102,7 @@ const finalizeCommit = async (title, description, commitData, currentBranch, tes
 };
 
 
-export default async function commit(config, testMode) {
+export default async function commit(config, testMode, debugMode) {
   if (!config) {
     return;
   }
@@ -114,7 +114,11 @@ export default async function commit(config, testMode) {
   }
 
   if (testMode) {
-    utils.log('test mode enabled - commit will not be performed', 'warning');
+    utils.log('test mode enabled (commit will not be performed)', 'warning');
+  }
+
+  if (debugMode) {
+    utils.log('debug mode enabled (additional visible logs)', 'debug');
   }
 
   // Get current git branch for version change option "only on release branch"
@@ -128,8 +132,20 @@ export default async function commit(config, testMode) {
     return;
   }
 
+  if (config.format === 'custom') {
+    const formatValid = utils.validateCustomFormatPattern(config.customFormat);
+    if (formatValid !== true) {
+      utils.log(`Invalid custom format - ${formatValid}`, 'error');
+      return;
+    }
+  }
+
+  const formatNeedsScope = config.format === 'custom'
+    ? utils.customFormatHasScope(config.customFormat)
+    : config.format >= 5;
+
   const noScope = !config.scopes || (config.scopes && config.scopes.length === 0);
-  if (config.format >= 5 && noScope) {
+  if (formatNeedsScope && noScope) {
     utils.log('no scopes defined - update config or format option', 'error');
     return;
   }
@@ -137,10 +153,35 @@ export default async function commit(config, testMode) {
   // Warn if using default example scope and skip AI suggestions
   const hasDefaultScope = config.scopes && config.scopes.length === 1 && config.scopes[0].value === 'example';
   if (hasDefaultScope) {
-    utils.log('You are using the default scope "example" - customize your scopes in commit-config.json or run format-commit --config', 'warning');
+    utils.log('You are using the default scope "example" - customize your scopes in commit-config.json or run `format-commit --config`', 'warning');
     utils.log('AI suggestions skipped - configure your scopes', 'warning');
   }
 
+  // Collect custom field values early (needed before AI and classic flows)
+  let cancelled = false;
+  let customFieldValues = {};
+  if (config.format === 'custom') {
+    const fields = utils.getCustomFields(config.customFormat);
+    for (const label of fields) {
+      const resp = await prompts({
+        type: 'text',
+        name: 'value',
+        message: `${label}?`,
+        validate: v => (!v || !v.trim()) ? `${label} cannot be empty` : true,
+      }, {
+        onCancel: () => {
+          cancelled = true;
+          return false;
+        },
+      });
+      if (cancelled) {
+        utils.log('commit cancelled', 'error');
+        return;
+      }
+      customFieldValues[label] = resp.value;
+    }
+  }
+
   let commitTitle = null;
   let useAISuggestion = false;
 
@@ -150,7 +191,7 @@ export default async function commit(config, testMode) {
     let suggestions = [];
 
     try {
-      suggestions = await aiService.generateCommitSuggestions(config, testMode);
+      suggestions = await aiService.generateCommitSuggestions(config, debugMode, customFieldValues);
     } catch (err) {
       utils.log(`AI suggestions failed (${err.message})`, 'warning');
     }
@@ -188,7 +229,7 @@ export default async function commit(config, testMode) {
               }
 
               // Parse and validate format, type, and scope
-              const result = utils.parseAndNormalizeCommitTitle(val, config);
+              const result = utils.parseAndNormalizeCommitTitle(val, config, customFieldValues);
               if (result.error) {
                 return result.error;
               }
@@ -204,7 +245,7 @@ export default async function commit(config, testMode) {
           );
 
           // Normalize the final title (correct case)
-          const result = utils.parseAndNormalizeCommitTitle(rawTitle, config);
+          const result = utils.parseAndNormalizeCommitTitle(rawTitle, config, customFieldValues);
           commitTitle = result.normalized;
           useAISuggestion = true;
         } catch (err) {
@@ -217,8 +258,6 @@ export default async function commit(config, testMode) {
     }
   }
 
-  let cancelled = false;
-
   // If AI suggestion was accepted, only ask for description, version, and push
   if (useAISuggestion) {
     const commit = await prompts([
@@ -249,7 +288,7 @@ export default async function commit(config, testMode) {
         validate: val => utils.validVersion(val),
       },
       {
-        type: 'confirm',
+        type: testMode ? null : 'confirm',
         name: 'pushAfterCommit',
         message: 'Push changes?',
         initial: false,
@@ -279,7 +318,7 @@ export default async function commit(config, testMode) {
       choices: config.types,
     },
     {
-      type: config.format >= 5 ? 'select' : null,
+      type: formatNeedsScope ? 'select' : null,
       name: 'scope',
       message: 'Scope',
       choices: config.scopes,
@@ -306,7 +345,10 @@ export default async function commit(config, testMode) {
         if (!val || val.trim().length === 0) {
           return 'Commit title cannot be empty';
         }
-        const fullTitle = utils.formatCommitTitle(typeScope.type, val, config.format, typeScope.scope);
+        const fullTitle = utils.formatCommitTitle(
+          typeScope.type, val, config.format, typeScope.scope,
+          config.customFormat, customFieldValues
+        );
         return utils.validCommitTitle(fullTitle, config.minLength, config.maxLength);
       },
     },
@@ -359,7 +401,9 @@ export default async function commit(config, testMode) {
     typeScope.type,
     commit.title,
     config.format,
-    typeScope.scope
+    typeScope.scope,
+    config.customFormat,
+    customFieldValues
   );
 
   await finalizeCommit(commitTitle, commit.description, commit, currentBranch, testMode);

package/lib/create-branch.js

@@ -23,14 +23,36 @@ export default async function createBranch(config, testMode) {
     return;
   }
 
+  const isCustom = config.branchFormat === 'custom';
+  const customHasScope = isCustom && config.customBranchFormat && utils.customBranchFormatHasScope(config.customBranchFormat);
+  const needsScope = config.branchFormat === 2 || customHasScope;
+
   const noScope = !config.scopes || (config.scopes && config.scopes.length === 0);
-  if (config.branchFormat === 2 && noScope) {
+  if (needsScope && noScope) {
     utils.log('no scopes defined - update config or branch format option', 'error');
     return;
   }
 
+  if (isCustom) {
+    const formatValid = utils.validateCustomBranchFormatPattern(config.customBranchFormat);
+    if (formatValid !== true) {
+      utils.log(`Invalid custom branch format - ${formatValid}`, 'error');
+      return;
+    }
+  }
+
+  // Collect custom fields if custom format
+  const customFields = isCustom ? utils.getCustomBranchFields(config.customBranchFormat) : [];
+  const customFieldPrompts = customFields.map(field => ({
+    type: 'text',
+    name: `custom_${field}`,
+    message: `${field}?`,
+    validate: val => utils.validBranchCustomField(val, field),
+  }));
+
   let cancelled = false;
   const branch = await prompts([
+    ...customFieldPrompts,
     {
       type: 'select',
       name: 'type',
@@ -38,7 +60,7 @@ export default async function createBranch(config, testMode) {
       choices: config.types,
     },
     {
-      type: config.branchFormat === 2 ? 'select' : null,
+      type: needsScope ? 'select' : null,
       name: 'scope',
       message: 'Scope',
       choices: config.scopes,
@@ -50,7 +72,7 @@ export default async function createBranch(config, testMode) {
       validate: val => utils.validBranchDescription(val, config.maxLength),
     },
     {
-      type: 'confirm',
+      type: testMode ? null : 'confirm',
       name: 'checkoutAfterCreate',
       message: 'Switch to the new branch after creation?',
       initial: true,
@@ -67,13 +89,21 @@ export default async function createBranch(config, testMode) {
     return;
   }
 
+  // Build custom field values from prompt answers
+  const customFieldValues = {};
+  for (const field of customFields) {
+    customFieldValues[field] = branch[`custom_${field}`];
+  }
+
   // Format branch name and create it
   utils.log('create branch...');
   const branchName = utils.formatBranchName(
     branch.type,
     branch.description,
     config.branchFormat,
-    branch.scope
+    branch.scope,
+    config.customBranchFormat,
+    customFieldValues
   );
 
   if (testMode) {

package/lib/index.js

@@ -26,7 +26,8 @@ program
   .version('0.3.1')
   .option('-b, --branch', 'create a new branch with standardized naming')
   .option('-c, --config', 'generate a configuration file on your project for format-commit')
-  .option('-t, --test', 'start without finalize commit (for tests)');
+  .option('-t, --test', 'start without finalize commit (for tests)')
+  .option('-d, --debug', 'display additional logs');
 
 try {
   program.parse(process.argv);
@@ -49,7 +50,7 @@ try {
       utils.log('no configuration found', 'warning');
       const setupResult = await setup(true);
       if (setupResult && setupResult.commitAfter) {
-        commit(setupResult.config, opts.test);
+        commit(setupResult.config, opts.test, opts.debug);
       }
     } else {
       if (opts.branch) {
@@ -57,7 +58,7 @@ try {
         createBranch(JSON.parse(data), opts.test);
         return;
       }
-      commit(JSON.parse(data), opts.test);
+      commit(JSON.parse(data), opts.test, opts.debug);
     }
   });
 })();

package/lib/options.json

@@ -1,14 +1,14 @@
 {
   "configFile": "commit-config",
   "commitFormats": [
-    { "value": 1, "title": "(type) Name" },
-    { "value": 2, "title": "(type) name" },
-    { "value": 3, "title": "type: Name"  },
-    { "value": 4, "title": "type: name" },
-    { "value": 5, "title": "type(scope) Name" },
-    { "value": 6, "title": "type(scope) name" },
-    { "value": 7, "title": "type(scope): Name" },
-    { "value": 8, "title": "type(scope): name" }
+    { "value": 1, "title": "(type) Description" },
+    { "value": 2, "title": "(type) description" },
+    { "value": 3, "title": "type: Description"  },
+    { "value": 4, "title": "type: description" },
+    { "value": 5, "title": "type(scope) Description" },
+    { "value": 6, "title": "type(scope) description" },
+    { "value": 7, "title": "type(scope): Description" },
+    { "value": 8, "title": "type(scope): description" }
   ],
   "branchFormats": [
     { "value": 1, "title": "type/description" },

package/lib/setup.js

@@ -1,4 +1,5 @@
 import prompts from 'prompts';
+import kleur from 'kleur';
 import fs, { readFileSync } from 'fs';
 import * as utils from './utils.js';
 import * as envUtils from './env-utils.js';
@@ -29,13 +30,31 @@ export default async function setup(askForCommitAfter) {
       type: 'select',
       name: 'format',
       message: 'Commit messages nomenclature',
-      choices: options.commitFormats,
+      choices: [
+        ...options.commitFormats,
+        { value: 'custom', title: kleur.gray('Custom - define your own pattern') },
+      ],
+    },
+    {
+      type: prev => prev === 'custom' ? 'text' : null,
+      name: 'customFormat',
+      message: 'Custom format pattern (e.g. `{Issue ID} - type - scope - Description`)',
+      validate: val => utils.validateCustomFormatPattern(val),
     },
     {
       type: 'select',
       name: 'branchFormat',
       message: 'Branch names nomenclature',
-      choices: options.branchFormats,
+      choices: [
+        ...options.branchFormats,
+        { value: 'custom', title: kleur.gray('Custom - define your own pattern') },
+      ],
+    },
+    {
+      type: prev => prev === 'custom' ? 'text' : null,
+      name: 'customBranchFormat',
+      message: 'Custom branch format pattern (e.g. `{Issue ID}-type/description`)',
+      validate: val => utils.validateCustomBranchFormatPattern(val),
     },
     {
       type: 'number',
@@ -196,13 +215,20 @@ export default async function setup(askForCommitAfter) {
   }
 
   // Parse prompt data and write config file
+  const needsScope = (
+    (configChoices.format !== 'custom' && configChoices.format >= 5) ||
+    (configChoices.format === 'custom' && utils.customFormatHasScope(configChoices.customFormat)) ||
+    configChoices.branchFormat === 2 ||
+    (configChoices.branchFormat === 'custom' && utils.customBranchFormatHasScope(configChoices.customBranchFormat))
+  );
+
   const config = {
     format: configChoices.format,
+    customFormat: configChoices.format === 'custom' ? configChoices.customFormat : undefined,
     branchFormat: configChoices.branchFormat,
+    customBranchFormat: configChoices.branchFormat === 'custom' ? configChoices.customBranchFormat : undefined,
     types: defaultConfig.types,
-    scopes: (configChoices.format >= 5 || configChoices.branchFormat === 2)
-      ? defaultConfig.scopes
-      : undefined,
+    scopes: needsScope ? defaultConfig.scopes : undefined,
     minLength: configChoices.minLength,
     maxLength: configChoices.maxLength,
     changeVersion: configChoices.changeVersion,

package/lib/utils.js

@@ -1,5 +1,6 @@
 import { execSync } from 'child_process';
 import kleur from 'kleur';
+import { magenta } from 'kleur/colors';
 
 
 const { gray, bold, red, green, yellow } = kleur;
@@ -53,7 +54,199 @@ const validVersion = (version) => {
   return true;
 };
 
-const formatCommitTitle = (type, title, format, scope = '*') => {
+const applyCasing = (value, casing) => {
+  switch (casing) {
+    case 'lower': return value.toLowerCase();
+    case 'upper': return value.toUpperCase();
+    case 'capitalize': return value.charAt(0).toUpperCase() + value.slice(1).toLowerCase();
+    default: return value;
+  }
+};
+
+const detectCasing = (word) => {
+  if (word === word.toLowerCase()) { return 'lower'; }
+  if (word === word.toUpperCase()) { return 'upper'; }
+  return 'capitalize';
+};
+
+const parseCustomFormat = (pattern) => {
+  const regex = /\{([^}]+)\}|\b(type|scope|description)\b/gi;
+  const segments = [];
+  let lastIndex = 0;
+  let match;
+
+  while ((match = regex.exec(pattern)) !== null) {
+    // Add literal text before this match
+    if (match.index > lastIndex) {
+      segments.push({ type: 'literal', value: pattern.slice(lastIndex, match.index) });
+    }
+
+    if (match[1] !== undefined) {
+      // {field} placeholder
+      segments.push({ type: 'field', label: match[1] });
+    } else {
+      // keyword (type, scope, description)
+      segments.push({
+        type: 'keyword',
+        keyword: match[2].toLowerCase(),
+        case: detectCasing(match[2]),
+      });
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  // Add trailing literal text
+  if (lastIndex < pattern.length) {
+    segments.push({ type: 'literal', value: pattern.slice(lastIndex) });
+  }
+
+  return segments;
+};
+
+const customFormatHasScope = (pattern) => /\bscope\b/i.test(pattern);
+
+const customBranchFormatHasScope = (pattern) => customFormatHasScope(pattern);
+
+const getCustomFields = (pattern) => {
+  const fields = [];
+  const regex = /\{([^}]+)\}/g;
+  let match;
+  while ((match = regex.exec(pattern)) !== null) {
+    fields.push(match[1]);
+  }
+  return fields;
+};
+
+const validateCustomFormatPattern = (pattern) => {
+  if (!pattern || !pattern.trim()) {
+    return 'Pattern cannot be empty';
+  }
+  if (!/\btype\b/i.test(pattern)) {
+    return 'Pattern must contain the "type" keyword';
+  }
+  if (!/\bdescription\b/i.test(pattern)) {
+    return 'Pattern must contain the "description" keyword';
+  }
+  // Check balanced braces
+  let depth = 0;
+  for (const ch of pattern) {
+    if (ch === '{') { depth++; }
+    if (ch === '}') { depth--; }
+    if (depth < 0) { return 'Unbalanced braces in pattern'; }
+  }
+  if (depth !== 0) { return 'Unbalanced braces in pattern'; }
+  return true;
+};
+
+const parseCustomBranchFormat = (pattern) => {
+  const regex = /\{([^}]+)\}|\b(type|scope|description)\b/gi;
+  const segments = [];
+  let lastIndex = 0;
+  let match;
+
+  while ((match = regex.exec(pattern)) !== null) {
+    if (match.index > lastIndex) {
+      segments.push({ type: 'literal', value: pattern.slice(lastIndex, match.index) });
+    }
+
+    if (match[1] !== undefined) {
+      segments.push({ type: 'field', label: match[1] });
+    } else {
+      segments.push({
+        type: 'keyword',
+        keyword: match[2].toLowerCase(),
+        case: detectCasing(match[2]),
+      });
+    }
+
+    lastIndex = match.index + match[0].length;
+  }
+
+  if (lastIndex < pattern.length) {
+    segments.push({ type: 'literal', value: pattern.slice(lastIndex) });
+  }
+
+  return segments;
+};
+
+const validateCustomBranchFormatPattern = (pattern) => {
+  if (!pattern || !pattern.trim()) {
+    return 'Pattern cannot be empty';
+  }
+  if (!/\btype\b/i.test(pattern)) {
+    return 'Pattern must contain the "type" keyword';
+  }
+  if (!/\bdescription\b/i.test(pattern)) {
+    return 'Pattern must contain the "description" keyword';
+  }
+  // Check balanced braces
+  let depth = 0;
+  for (const ch of pattern) {
+    if (ch === '{') { depth++; }
+    if (ch === '}') { depth--; }
+    if (depth < 0) { return 'Unbalanced braces in pattern'; }
+  }
+  if (depth !== 0) { return 'Unbalanced braces in pattern'; }
+  // Validate literal parts (separators) are branch-safe
+  const segments = parseCustomBranchFormat(pattern);
+  const invalidBranchChars = /[~^:?*[\\\s]/;
+  for (const seg of segments) {
+    if (seg.type !== 'literal') { continue; }
+    if (invalidBranchChars.test(seg.value)) {
+      return 'Pattern contains characters invalid in branch names (spaces, ~, ^, :, ?, *, [, \\)';
+    }
+    if (seg.value.includes('..')) {
+      return 'Pattern cannot contain ".." (invalid in branch names)';
+    }
+    if (seg.value.includes('//')) {
+      return 'Pattern cannot contain "//" (invalid in branch names)';
+    }
+  }
+  return true;
+};
+
+const getCustomBranchFields = (pattern) => getCustomFields(pattern);
+
+const sanitizeBranchPart = (value) => {
+  return value
+    .replace(/\s+/g, '-')
+    .replace(/[^a-zA-Z0-9-]/g, '')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '');
+};
+
+const formatCustomBranchName = (type, description, segments, scope, customFieldValues = {}) => {
+  return segments.map(seg => {
+    if (seg.type === 'literal') { return seg.value; }
+    if (seg.type === 'field') { return sanitizeBranchPart(customFieldValues[seg.label] || ''); }
+    if (seg.type === 'keyword') {
+      switch (seg.keyword) {
+        case 'type': return applyCasing(type, seg.case);
+        case 'scope': return applyCasing(scope || '', seg.case);
+        case 'description': return applyCasing(sanitizeBranchPart(description), seg.case);
+      }
+    }
+    return '';
+  }).join('');
+};
+
+const formatCustomCommitTitle = (type, description, segments, scope, customFieldValues = {}) => {
+  return segments.map(seg => {
+    if (seg.type === 'literal') { return seg.value; }
+    if (seg.type === 'field') { return customFieldValues[seg.label] || ''; }
+    if (seg.type === 'keyword') {
+      switch (seg.keyword) {
+        case 'type': return applyCasing(type, seg.case);
+        case 'scope': return applyCasing(scope || '', seg.case);
+        case 'description': return applyCasing(description, seg.case);
+      }
+    }
+    return '';
+  }).join('');
+};
+
+const formatCommitTitle = (type, title, format, scope = '*', customFormat, customFieldValues) => {
   // Handle empty title
   if (!title || title.trim().length === 0) {
     return '';
@@ -61,6 +254,11 @@ const formatCommitTitle = (type, title, format, scope = '*') => {
 
   const trimmedTitle = title.trim();
 
+  if (format === 'custom' && customFormat) {
+    const segments = parseCustomFormat(customFormat);
+    return formatCustomCommitTitle(type, trimmedTitle, segments, scope, customFieldValues);
+  }
+
   switch (format) {
     case 1:
     default:
@@ -104,29 +302,43 @@ const log = (message, type) => {
     case 'warning':
       msg = yellow(msg);
       break;
+    case 'debug':
+      msg = magenta(msg);
+      break;
   }
   console.log(`${date} ${type === 'error' ? red(msg) : (type === 'success' ? green(msg) : msg)}`);
 };
 
-const validBranchDescription = (description, maxLength) => {
-  if (description.length < 1) {
-    return 'Branch description cannot be empty';
-  }
-  if (description.length > maxLength) {
-    return `Branch description too long (max ${maxLength} characters)`;
+const validBranchCustomField = (value, label) => {
+  if (!value || value.trim().length < 1) {
+    return `${label} cannot be empty`;
   }
   const invalidChars = /[~^:?*[\\\s]/;
-  if (invalidChars.test(description)) {
-    return 'Branch description contains invalid characters (spaces, ~, ^, :, ?, *, [, \\)';
+  if (invalidChars.test(value)) {
+    return `${label} contains invalid characters (spaces, ~, ^, :, ?, *, [, \\)`;
+  }
+  if (value.startsWith('.') || value.startsWith('-') ||
+    value.endsWith('.') || value.endsWith('-')) {
+    return `${label} cannot start or end with . or -`;
   }
-  if (description.startsWith('.') || description.startsWith('-') ||
-    description.endsWith('.') || description.endsWith('-')) {
-    return 'Branch description cannot start or end with . or -';
+  return true;
+};
+
+const validBranchDescription = (description, maxLength) => {
+  const base = validBranchCustomField(description, 'Branch description');
+  if (base !== true) { return base; }
+  if (description.length > maxLength) {
+    return `Branch description too long (max ${maxLength} characters)`;
   }
   return true;
 };
 
-const formatBranchName = (type, description, format, scope = null) => {
+const formatBranchName = (type, description, format, scope = null, customBranchFormat = null, customFieldValues = {}) => {
+  if (format === 'custom' && customBranchFormat) {
+    const segments = parseCustomBranchFormat(customBranchFormat);
+    return formatCustomBranchName(type, description, segments, scope, customFieldValues);
+  }
+
   const cleanDescription = description
     .toLowerCase()
     .replace(/\s+/g, '-')
@@ -160,7 +372,85 @@ const checkBranchExists = (branchName) => {
 };
 
 /** Parse and validate commit title format, auto-correct case */
-const parseAndNormalizeCommitTitle = (title, config) => {
+const parseAndNormalizeCommitTitle = (title, config, customFieldValues = {}) => {
+  // Custom format parsing
+  if (config.format === 'custom' && config.customFormat) {
+    const segments = parseCustomFormat(config.customFormat);
+
+    // Build dynamic regex from segments
+    const captureNames = [];
+    let regexParts = [];
+    const captureSegments = segments.filter(s => s.type === 'keyword' || s.type === 'field');
+
+    for (let i = 0; i < segments.length; i++) {
+      const seg = segments[i];
+      if (seg.type === 'literal') {
+        regexParts.push(seg.value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'));
+      } else if (seg.type === 'keyword' || seg.type === 'field') {
+        const isLast = captureSegments.indexOf(seg) === captureSegments.length - 1;
+        captureNames.push(seg);
+        regexParts.push(isLast ? '(.+)' : '(.+?)');
+      }
+    }
+
+    const dynamicRegex = new RegExp('^' + regexParts.join('') + '$');
+    const match = title.match(dynamicRegex);
+
+    if (!match) {
+      const exampleTitle = formatCommitTitle(
+        config.types[0].value, 'description', config.format,
+        config.scopes?.[0]?.value, config.customFormat, customFieldValues
+      );
+      return { error: `Wrong format. Expected: "${exampleTitle}"` };
+    }
+
+    let type, scope, message;
+    const fieldValues = {};
+
+    for (let i = 0; i < captureNames.length; i++) {
+      const seg = captureNames[i];
+      const val = match[i + 1].trim();
+      if (seg.type === 'keyword') {
+        switch (seg.keyword) {
+          case 'type': type = val; break;
+          case 'scope': scope = val; break;
+          case 'description': message = val; break;
+        }
+      } else if (seg.type === 'field') {
+        fieldValues[seg.label] = val;
+      }
+    }
+
+    // Validate type
+    if (!type) {
+      return { error: 'Could not detect type in commit title' };
+    }
+    const validType = config.types.find(t => t.value.toLowerCase() === type.toLowerCase());
+    if (!validType) {
+      const validTypes = config.types.map(t => t.value).join(', ');
+      return { error: `Invalid type "${type}". Valid types: ${validTypes}` };
+    }
+
+    // Validate scope if present
+    let validScope = scope;
+    if (scope) {
+      if (!config.scopes || config.scopes.length === 0) {
+        return { error: 'Scope not allowed in current format configuration' };
+      }
+      const foundScope = config.scopes.find(s => s.value.toLowerCase() === scope.toLowerCase());
+      if (!foundScope) {
+        const validScopes = config.scopes.map(s => s.value).join(', ');
+        return { error: `Invalid scope "${scope}". Valid scopes: ${validScopes}` };
+      }
+      validScope = foundScope.value;
+    }
+
+    const normalized = formatCustomCommitTitle(
+      validType.value, message, segments, validScope, fieldValues
+    );
+    return { normalized };
+  }
+
   let type, scope, message, detectedFormatGroup;
 
   // Try different format patterns
@@ -202,7 +492,7 @@ const parseAndNormalizeCommitTitle = (title, config) => {
   if (detectedFormatGroup !== expectedFormatGroup) {
     const exampleTitle = formatCommitTitle(
       config.types[0].value,
-      'name',
+      'description',
       config.format,
       config.scopes?.[0]?.value
     );
@@ -250,11 +540,21 @@ export {
   validCommitTitle,
   validCommitTitleSetupLength,
   validBranchDescription,
+  validBranchCustomField,
   validVersion,
   formatCommitTitle,
   formatBranchName,
   checkBranchExists,
   parseAndNormalizeCommitTitle,
+  parseCustomFormat,
+  customFormatHasScope,
+  getCustomFields,
+  validateCustomFormatPattern,
+  parseCustomBranchFormat,
+  validateCustomBranchFormatPattern,
+  formatCustomBranchName,
+  customBranchFormatHasScope,
+  getCustomBranchFields,
   handleCmdExec,
   log,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "format-commit",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Lightweight CLI to standardize commit messages with AI-powered suggestions",
   "license": "MIT",
   "author": "Thomas BARKATS",