goal 2.1.114

Goal - Automated git push with enterprise-grade commit intelligence, smart conventional commit generation based on deep code analysis, and interactive release workflow management.

claude-taking-longer-than-usual.webm

Goal

Goal is your release autopilot: a CLI that runs tests, writes conventional commits, updates changelogs, bumps versions, and publishes packages for you—while keeping you in control with clear prompts or full automation.

Why you might need Goal

• Solo dev finishing a feature → run one command, get a polished commit, synced versions, and a tagged release without memorizing git plumbing.
• Team ready for a patch fix → ensure the changelog, VERSION file, and package registry stay in lockstep, even when multiple people touch the repo.
• CI/CD pipeline → same command powers nightly builds, preview releases, or fully automated publishing.

What you get out of the box

1. 🔍 Context-aware diagnostics – detects repo state, project types, missing remotes, config drift.
2. 🧠 Commit intelligence – auto-scoped conventional messages that explain what changed, what was tested, and the scale of work.
3. 🏷️ Release hygiene – synchronized VERSION files, changelog updates, git tags, and optional registry publish.
4. ⚙️ Multi-language support – Python, Node.js, Rust, Go, Java, .NET, PHP, Ruby, and hybrid repos.
5. 🤖 Prompted or headless – run interactively (goal) or fire-and-forget in CI with goal --all.

Three real-life flows

# 1. First-time setup in a folder without git
goal           # Goal offers to init git, add a remote, then re-run the workflow.

# 2. Everyday feature release
goal push      # Runs tests, suggests a commit, bumps patch, updates changelog, pushes, tags.

# 3. CI/CD or cron-driven release
goal --all --bump minor   # Non-interactive; perfect for nightly builds or release pipelines.

🆕 What's New in v2.2.0

Wizard Setup, License Management & Multi-Author Support — Complete project initialization, professional license handling, and team collaboration features

✨ New Features

🧙‍♂️ Interactive Setup Wizard

• One-command project initialization with goal wizard
• Guided git repository setup and remote configuration
• Interactive user configuration (name, email, license)
• Project configuration with versioning and commit strategies
• Complete setup summary with next steps

# New project setup in one command
goal wizard

📄 Professional License Management

• Create and update LICENSE files with 8 common license templates
• Custom license template support for proprietary licenses
• SPDX license ID validation with helpful error messages
• License compatibility checking between different licenses
• Automatic template variable substitution ({year}, {fullname})

# Create MIT license
goal license create MIT --fullname "Your Name"

# Check license compatibility
goal license check MIT Apache-2.0

👥 Multi-Author Project Support

• Team-based author management stored in project configuration
• Import authors from git history automatically
• Co-author support in commit messages with --co-author flag
• Export team list to CONTRIBUTORS.md
• Find authors by name, email, or alias

# Add team members
goal authors add "Jane Doe" [e-mail] --role "Developer"

# Commit with co-authors
goal commit --co-author "Jane Doe <[e-mail]>"

🛠️ Enhanced Commands

All new commands integrate seamlessly with existing Goal workflows:

# Complete workflow with co-authors
goal push --co-author "Jane Doe <[e-mail]>"

# Automated release with team attribution
goal --all --co-author "Team <[e-mail]>"

🆕 What's New in v2.1.99

Security Validation & Proactive .gitignore Management — Automatic protection against large files, API tokens, and unwanted dot folders

✨ New Security Features

🔒 File Size Validation

• Automatically blocks files larger than 10MB (configurable)
• Prevents GitHub push failures due to file size limits
• Clear error messages with file size information

🔑 API Token Detection

• Scans for exposed API tokens before commit
• Supports GitHub, AWS, Slack, Stripe, GitLab patterns
• Detects private keys and sensitive credentials
• Blocks commit with location details

📁 Proactive .gitignore Management

• Automatically detects dot folders (.idea, .vscode, etc.)
• Adds problematic folders to .gitignore before commit
• Unstages files that should be ignored
• Respects existing whitelist patterns (!.vscode)
• Safe dot files are never ignored: .gitignore, .github/, .editorconfig, .gitattributes

🛡️ Security Validation in Action

# Before commit, Goal automatically checks:
goal push

# Also works with automation modes:
goal -a          # Full automation with validation
goal --all       # All stages with validation
goal --yes       # Auto-confirm with validation

# Output examples:
✅ Added 2 dot folder(s)/file(s) to .gitignore: .idea, .DS_Store
  → Unstaged: .idea
  → Unstaged: .DS_Store

# Or blocks dangerous commits:
❌ Validation Error: File secrets.db is 15.2MB, which exceeds the limit of 10MB
❌ Validation Error: Potential GitHub Personal Access token detected in .env:5

⚙️ Configuration Options

# goal.yaml
advanced:
  file_validation:
    max_file_size_mb: 10          # File size limit
    block_large_files: true       # Block or just warn
    detect_api_tokens: true       # Enable token detection
    auto_manage_gitignore: true   # Auto-update .gitignore
    auto_add_dot_folders: true    # Auto-add dot folders
    known_dot_folders:           # Custom list of folders to ignore
      - .idea
      - .vscode
      - .DS_Store
      - .code2llm_cache
      - .llm

🚀 Bypass Options

# Force commit (not recommended for security)
goal push --force

# Dry run to check what would be blocked
goal push --dry-run

🆕 What's New in v2.1.65

TODO Management & Publishing Fixes — Automatic issue tracking and reliable PyPI publishing

✨ New Features

🎫 Automatic TODO Management

• goal doctor --todo adds detected issues to TODO.md
• Unique ticket IDs prevent duplicates
• Rich formatting with severity icons
• Timestamped sections for tracking

🔧 Publishing Improvements

• Fixed "cannot access local variable 'Path'" error
• Better handling of ~/.pypirc authentication
• Improved error messages and debugging
• Support for both token and config-based auth

🛠️ Enhanced Diagnostics

• Better error detection in project configuration
• More reliable build process
• Improved artifact management

📋 Example Usage

# Check version
goal -v

# Diagnose and track issues
goal doctor --todo
goal doctor -t

# Full workflow with TODO tracking
goal --all --todo
goal -a -t

# Standard workflow
goal --all

# Check project health
goal doctor

## 📚 Previous Features (v2.1)

> **Smart Commit Intelligence** — commit bodies that answer *what changed, what was tested, and at what scale*

❌ BEFORE: refactor(core): add testing, logging, validation
✅ AFTER:  feat(goal): intelligent code analysis pipeline

changes:
  - file: cli.py
    area: cli
    added: [ensure_git_repository, ensure_remote, _run_git_verbose]
    modified: [push]
  - file: test_clone_repo.py
    area: test
    new_tests: 3

testing:
  new_tests: 3
  scenarios:
    - auto_mode_skips
    - init_and_add_remote
    - clone_option_with_valid_url

stats:
  lines: "+210/-45 (net +165)"
  files: 2
  complexity: "Stable complexity"

Interactive Git Setup — goal now guides you through repository configuration when no git repo is found

⚠  Not a git repository.

What would you like to do?
  [1] Initialize git here and connect to a remote  (keeps local files in 'myproject/')
  [2] Clone a remote repository into this directory  (downloads remote files)
  [3] Initialize a local-only git repository        (no remote)
  [4] Exit

📖 Full Documentation | 📂 Examples

Features

• 🚀 Interactive workflow - Confirms each stage (test, commit, push, publish) with Y/n prompts
• 🧠 Smart commit messages - Generates conventional commits based on diff analysis
• 🎯 Enhanced Summary - Business-value focused messages with capabilities, metrics, relations
• 👤 User configuration - Auto-detects git user info and license preferences (stored in ~/.goal)
• 📄 Smart metadata management - Automatically updates author and license in project files
• 📝 README automation - Updates license badges and author sections automatically
• 🔍 Version validation - Checks registry versions and README badge consistency
• 📦 Multi-language support - Python, Node.js, Rust, Go, Ruby, PHP, .NET, Java
• 🏷️ Version management - Automatic version bumping and synchronization across project files
• 📝 Changelog updates - Maintains CHANGELOG.md with version history
• 🐳 CI/CD ready - --yes flag for automated workflows
• 🧪 Test integration - Runs project-specific test commands before committing
• 📦 Publish support - Publishes to package managers (PyPI, npm, crates.io, etc.)
• 🔒 Security validation - Blocks large files, detects API tokens, manages .gitignore automatically

Installation

pip install goal

Quick Start

1. Install Goal

pip install goal

2. Run goal in any project directory

cd my-project/
goal

Goal detects your situation and guides you interactively:

Scenario A: No git repository yet

⚠  Not a git repository.

What would you like to do?
  [1] Initialize git here and connect to a remote  (keeps local files in 'my-project/')
  [2] Clone a remote repository into this directory  (downloads remote files)
  [3] Initialize a local-only git repository        (no remote)
  [4] Exit
Choose [1]: 1

  → git init
✓ Initialized git repository.

Enter repository URL:
  SSH   example: [e-mail]:user/repo.git
  HTTP  example: https://github.com/user/repo.git
URL: [e-mail]:wronai/my-project.git

  → git remote add origin [e-mail]:wronai/my-project.git
✓ Remote 'origin' → [e-mail]:wronai/my-project.git

Fetching remote branches...
  → git fetch origin
  Remote is empty (no branches yet). Your local files will be the first push.

✓ Ready. Run 'goal' again to commit and push.

Scenario B: Git repo exists, no remote configured

⚠  No git remote configured.

Would you like to add a remote?
  [1] Add remote origin (connect to GitHub/GitLab/etc.)
  [2] Skip — commit locally without pushing
Choose [1]: 1

  → git remote add origin [e-mail]:wronai/my-project.git
  Verifying connection...
  ✓ Remote is reachable.
✓ Remote 'origin' → [e-mail]:wronai/my-project.git

Scenario C: Everything configured — the normal workflow

Detected project types: python
Will commit 5 files (+120/-15 lines, NET 105, 11% churn deletions)
Commit message: feat(api): add user authentication endpoint

Run tests? [Y/n]
Commit changes? [Y/n]
Push to remote? [Y/n]
Publish version 1.2.3? [Y/n]

Every git command is shown transparently (lines starting with →) so you always know what goal is doing.

3. Automation modes

# Full automation — tests, commit, push, publish (skips if no repo/remote)
goal -a

# Skip prompts but don't auto-publish
goal --yes

# Preview what would happen
goal --dry-run

Note: goal -a in a directory without a git repository will skip gracefully instead of failing. This is safe for CI/CD pipelines.

Running from a local clone

If you're working with the goal source code:

git clone https://github.com/wronai/goal.git
cd goal

# Use the local version without installing
python3 -m goal

# Or install in development mode
pip install -e .

Documentation

📚 Complete Documentation: docs/README.md

Key Topics

• Installation Guide - Detailed installation instructions
• Quick Start - Get started in 5 minutes
• Configuration Guide - Complete goal.yaml reference
• Examples - Real-world examples and use cases
• CI/CD Integration - Use Goal in pipelines
• Command Reference - All commands and options

Usage Examples

Basic interactive workflow

# Run full interactive workflow with default patch bump
goal

# Run with minor version bump
goal --bump minor

# Run without prompts (for CI/CD)
goal --yes

# Automate ALL stages without any prompts
goal --all

Real-world examples

1. Python project with pytest

# Make changes to your Python code
git add .

# Run the full workflow
goal

# Output:
# ✓ Detected project types: python
# ✓ Running tests: pytest tests/ -v
# ✓ Tests passed (23/23)
# ✓ Generated commit: feat(api): add user authentication endpoint
# ✓ Updated VERSION to 1.2.3
# ✓ Updated CHANGELOG.md
# ✓ Created tag v1.2.3
# ✓ Pushed to origin
# ? Publish to PyPI? [Y/n]: Y
# ✓ Published version 1.2.3

2. Node.js project with npm

# Quick patch release for bug fix
goal push --yes -m "fix: resolve memory leak in parser"

# Output:
# ✓ Detected project types: nodejs
# ✓ Running tests: npm test
# ✓ Tests passed
# ✓ Committed: fix: resolve memory leak in parser
# ✓ Updated package.json to 1.0.1
# ✓ Updated CHANGELOG.md
# ✓ Created tag v1.0.1
# ✓ Pushed to origin

3. Rust project with cargo

# Major release with breaking changes
goal push --bump major --yes

# Output:
# ✓ Detected project types: rust
# ✓ Running tests: cargo test
# ✓ All tests passed
# ✓ Generated commit: feat!: change public API structure
# ✓ Updated Cargo.toml to 2.0.0
# ✓ Updated CHANGELOG.md
# ✓ Created tag v2.0.0
# ✓ Pushed to origin
# ? Publish to crates.io? [Y/n]: Y
# ✓ Published crate v2.0.0

4. Publishing packages

# Publish only (after committing)
goal publish

# Or include publishing in the full workflow
goal --all  # Will publish automatically

Important: Goal automatically filters artifacts to upload only the current version, avoiding "File already exists" errors on PyPI.

If you see a "File already exists" error:

1. Clean and rebuild: rm -rf dist build && python -m build
2. Or bump version again: goal --bump patch
3. Check you're using the latest goal: python3 -m goal (in goal repo)

4. Multi-language project

# Project with both Python backend and Node.js frontend
goal info

# Output:
# === Project Information ===
# Project types: python, nodejs
# Current version: 1.5.0
# 
# Version files:
#   ✓ VERSION: 1.5.0
#   ✓ package.json: 1.5.0
#   ✓ pyproject.toml: 1.5.0

# Run release - updates both package.json and pyproject.toml
goal push --yes

5. Documentation updates

# Skip tests for docs-only changes
goal push --no-test -m "docs: update API documentation"

# Or let goal detect it's docs only
git add README.md docs/
goal push --yes

# Output:
# ✓ Detected project types: python
# ✓ Generated commit: docs: update API documentation
# ✓ Updated VERSION to 1.5.1
# ✓ Updated CHANGELOG.md
# ✓ Created tag v1.5.1
# ✓ Pushed to origin

6. CI/CD automation

# .github/workflows/release.yml
name: Release
on:
  push:
    branches: [main]
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - name: Install Goal
        run: pip install goal
      - name: Configure PyPI token
        run: echo "__token__=${{ secrets.PYPI_TOKEN }}" > ~/.pypirc
      - name: Release
        run: goal --all --bump patch

7. Dry run for preview

# Preview what will happen
goal push --dry-run --bump minor

# Output:
# === DRY RUN ===
# Project types: python
# Files to commit: 12 (+342/-15 lines)
#   - src/auth.py (+120/-5)
#   - tests/test_auth.py (+85/-0)
#   - docs/api.md (+137/-10)
# Commit message: feat(auth): add OAuth2 integration
# Version: 1.5.0 -> 1.6.0
# Version sync: VERSION, pyproject.toml
# Tag: v1.6.0

8. Custom commit message

# Override auto-generated message
goal push -m "feat: implement real-time notifications"

# Or use conventional commit format
goal push -m "fix(auth): resolve JWT token expiration issue"

9. Split commits for large changes

# Split changes into logical commits
goal push --split --yes

# Output:
# ✓ Committed docs: update README and API docs
# ✓ Committed feat: add user authentication system
# ✓ Committed test: add comprehensive test coverage
# ✓ Committed chore: update dependencies and CI config
# ✓ Committed release: v2.0.0

11. Security Validation Examples

# Goal automatically protects against security issues
goal push

# Example 1: Large file detected
# ❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB
# For security reasons, the commit has been blocked.
# To bypass this check, you can:
# 1. Remove the sensitive/large file(s)
# 2. Add the file(s) to .gitignore
# 3. Use --force to bypass validation (not recommended)

# Example 2: API token detected
# ❌ Validation Error: Potential GitHub Personal Access token detected in .env:5
# For security reasons, the commit has been blocked.

# Example 3: Dot folder auto-management
# ✅ Added 3 dot folder(s)/file(s) to .gitignore: .idea, .vscode, .DS_Store
#   → Unstaged: .idea
#   → Unstaged: .vscode
#   → Unstaged: .DS_Store

12. Skip specific steps

# Skip version bump for hotfix
goal push --yes --no-version-sync -m "hotfix: critical security patch"

# Skip changelog for minor tweak
goal push --yes --no-changelog -m "style: fix linting issues"

# Skip tag creation for experimental feature
goal push --yes --no-tag -m "feat: experimental AI integration"

Using the push command directly

# Interactive push with prompts
goal push

# Automatic push without prompts
goal push --yes

# Dry run to see what would happen
goal push --dry-run

# Custom commit message
goal push -m "feat: add new authentication system"

# Skip specific steps
goal push --no-tag --no-changelog

# With version bump
goal push --bump minor

# Markdown output for CI/CD logs
goal push --markdown

Version management

# Check current version
goal version

# Bump specific version type
goal version --bump minor
goal version --bump major

# Check repository status
goal status

Supported Project Types

Goal automatically detects your project type and uses appropriate commands:

Language	Test Command	Publish Command	Version Files
Python	pytest	python -m build && twine upload dist/*	pyproject.toml, setup.py
Node.js	npm test	npm publish	package.json
Rust	cargo test	cargo publish	Cargo.toml
Go	go test ./...	git push origin --tags	go.mod (uses git tags)
Ruby	bundle exec rspec	gem build *.gemspec && gem push *.gem	*.gemspec
PHP	composer test	composer publish	composer.json
.NET	dotnet test	dotnet pack && dotnet nuget push *.nupkg	*.csproj
Java	mvn test	mvn deploy	pom.xml, build.gradle

Markdown Output

Goal outputs structured markdown by default (perfect for LLM consumption and CI/CD logs). Use --ascii to get the legacy console output.

# Default: markdown output
goal push
goal status

# Force legacy output
goal push --ascii
goal status --ascii

# Use with automation
goal --all > release.log

The markdown output includes:

• Front matter with metadata (command, version, file count)
• Structured sections for overview, files, and test results
• Code blocks for command outputs
• Summary with actions taken and next steps

Example output:

---
command: goal push
project_types: ["python"]
version_bump: "1.0.1 -> 1.0.2"
file_count: 7
---

# Goal Push Result

## Overview
**Project Type:** python
**Files Changed:** 7 (+1140/-99 lines)
**Version:** 1.0.1 → 1.0.2
...

See docs/markdown-output.md for detailed examples.

Command Reference

goal or goal push

Main command for the complete workflow.

Options:

• -v, --version: Show version and exit
• --bump, -b: Version bump type [patch|minor|major] (default: patch)
• --yes, -y: Skip all prompts (run automatically)
• --all, -a: Automate all stages including tests, commit, push, and publish
• --todo/--no-todo, -t: Add unfixed issues to TODO.md during doctor phase (default: no)
• --markdown/--ascii: Output format (default: markdown)
• --split: Create separate commits per change type (docs/code/ci/examples)
• --ticket: Ticket prefix to include in commit titles (overrides TICKERT)
• --no-tag: Skip creating git tag
• --no-changelog: Skip updating changelog
• --no-version-sync: Skip syncing version to project files
• --message, -m: Custom commit message
• --dry-run: Show what would be done without doing it

goal doctor

Diagnose and auto-fix common project configuration issues.

Options:

• --fix/--no-fix: Auto-fix issues (default: yes)
• --path, -p: Root directory to scan (default: .)
• --todo/--no-todo, -t: Add unfixed issues to TODO.md (default: no)

Examples:

goal doctor              # Diagnose and auto-fix
goal doctor --no-fix     # Diagnose only
goal doctor --todo       # Add issues to TODO.md
goal doctor -t           # Add issues to TODO.md (short form)

Split commits (per type)

When --split is enabled, Goal will create multiple commits:

• code: changes in goal/, src/, lib/, *.py
• docs: docs/*, README.md, *.md
• ci: .github/*, .gitlab/*, *.yml/*.yaml
• examples: examples/*
• other: everything else

Then it will create a final release metadata commit with version bump + changelog (unless disabled).

Ticket prefixing (TICKET)

Create a TICKET file in repository root:

prefix=ABC-123
format=[{ticket}] {title}

You can override it per run:

goal push --ticket ABC-123
goal push --split --ticket ABC-123
goal commit --ticket ABC-123

goal init

Initialize goal in current repository.

Creates:

• VERSION file with initial version 1.0.0
• CHANGELOG.md with standard template

goal status

Show current git status and version info.

Displays:

• Current version
• Current branch
• Staged files
• Unstaged/untracked files

goal version

Show or bump version.

Options:

• --type, -t: Version bump type [patch|minor|major] (default: patch)

goal wizard

Interactive guided setup for new projects.

Walks you through:

• Git repository initialization and remote configuration
• User configuration (name, email, license)
• Project configuration (name, description, versioning strategy)
• Complete setup summary with next steps

Options:

• --reset: Reset and reconfigure everything
• --skip-git: Skip git repository setup
• --skip-user: Skip user configuration
• --skip-project: Skip project configuration

goal license

Manage project licenses.

Subcommands:

• create <license_id>: Create LICENSE file
• update: Update existing LICENSE file
• validate: Validate LICENSE file
• info <license_id>: Show license information
• check <license1> <license2>: Check compatibility
• list: List available templates
• template <license_id>: Add/show custom templates

Examples:

goal license create MIT --fullname "Your Name"
goal license check MIT Apache-2.0
goal license list

goal authors

Manage project authors and team members.

Subcommands:

• list: List all project authors
• add <name> <email>: Add an author
• remove <email>: Remove an author
• update <email>: Update author info
• import: Import from git history
• export: Export to CONTRIBUTORS.md
• find <identifier>: Find author by name/email/alias
• current: Show current user info

Examples:

goal authors add "Jane Doe" [e-mail] --role "Developer"
goal authors list
goal authors import

Co-author Support

Add co-authors to commits:

goal commit --co-author "Jane Doe <[e-mail]>"
goal commit --co-author "Jane <[e-mail]>" --co-author "Bob <[e-mail]>"

Examples by Use Case

New Project Setup

# Interactive guided setup
goal wizard

📖 Full Wizard Example

License Management

# Create MIT license
goal license create MIT --fullname "Your Name"

# Check license compatibility
goal license check MIT Apache-2.0

📖 License Management Examples

Team Collaboration

# Add team members
goal authors add "Jane Doe" [e-mail] --role "Developer"

# Commit with co-authors
goal commit --co-author "Jane Doe <[e-mail]>"

📖 Multi-Author Project Examples

Development Workflow

# Make your changes...
git add some/files

# Run goal with interactive prompts
goal

# Prompts will appear:
# Run tests? [Y/n] - Runs pytest for Python projects
# Commit changes? [Y/n] - Creates smart commit message
# Push to remote? [Y/n] - Pushes to origin with tags
# Publish version 1.2.3? [Y/n] - Publishes to PyPI/npm/etc

Full Automation

# Automate everything - tests, commit, push, publish
goal --all

# Short form
goal -a

# With specific version bump
goal --all --bump minor

CI/CD Pipeline

# GitHub Actions example
- name: Deploy with Goal
  run: |
    goal push --yes --bump minor
    
# Or with --all flag
- name: Full release
  run: |
    goal --all --bump patch

Skip Testing in Quick Fixes

# Skip tests for documentation changes
goal push --yes -m "docs: update README"

Pre-release Workflow

# Check what will be done
goal push --dry-run --bump minor

# Run with specific version bump
goal push --bump minor

# Or skip publishing for internal releases
goal push --yes --no-tag

Working with Multiple Projects

# Monorepo with frontend and backend
# Structure:
# /backend (Python)
# /frontend (Node.js)
# /docs

# From root directory
goal info

# Output:
# Project types: python, nodejs
# Version files:
#   ✓ VERSION: 2.1.0
#   ✓ backend/pyproject.toml: 2.1.0
#   ✓ frontend/package.json: 2.1.0

# Release updates all projects
goal push --yes

Hotfix Workflow

# Critical fix - skip tests and version bump
goal push --yes --no-test --no-version-sync -m "hotfix: security patch"

# Then create proper release
goal push --bump patch -m "release: v1.2.1 with security fix"

Feature Branch Workflow

# On feature branch
goal push --yes --no-tag --no-publish

# After merge to main
goal push --bump minor --yes

Release Candidate

# Create RC version
goal push --bump patch -m "release: v2.0.0-rc1"

# After testing, promote to stable
goal push --bump patch -m "release: v2.0.0 stable"

Configuration

Goal uses goal.yaml for configuration. Run goal init to create it automatically with detected settings.

goal.yaml Structure

# goal.yaml - Goal configuration file
version: "1.0"

project:
  name: "my-project"           # Auto-detected from pyproject.toml/package.json
  type: ["python"]             # Auto-detected project types
  description: "My project"    # Auto-detected description

versioning:
  strategy: "semver"           # semver, calver, or date
  files:                       # Files to sync version to
    - "VERSION"
    - "pyproject.toml:version"
    - "package.json:version"
  bump_rules:                  # Auto-bump thresholds
    patch: 10                  # Files changed
    minor: 50                  # Lines added
    major: 200                 # Large changes

git:
  commit:
    strategy: "conventional"   # conventional, semantic, custom
    scope: "my-project"        # Default scope for commits
    templates:                 # Custom commit templates
      feat: "feat({scope}): {description}"
      fix: "fix({scope}): {description}"
      docs: "docs({scope}): {description}"
    classify_by:               # Classification methods
      - "file_extensions"
      - "directory_paths"
      - "line_stats"
      - "keywords_diff"
  changelog:
    enabled: true
    template: "keep-a-changelog"
    output: "CHANGELOG.md"
    sections: ["Added", "Changed", "Fixed", "Deprecated"]
  tag:
    enabled: true
    prefix: "v"
    format: "{prefix}{version}"

strategies:
  python:
    test: "pytest tests/ -v"
    build: "python -m build"
    publish: "twine upload dist/*"
  nodejs:
    test: "npm test"
    build: "npm run build"
    publish: "npm publish"

registries:
  pypi:
    url: "https://pypi.org/simple/"
    token_env: "PYPI_TOKEN"
  npm:
    url: "https://registry.npmjs.org/"
    token_env: "NPM_TOKEN"

hooks:
  pre_commit: ""               # Command to run before commit
  post_commit: ""              # Command to run after commit
  pre_push: ""                 # Command to run before push
  post_push: ""                # Command to run after push

advanced:
  auto_update_config: true     # Auto-update config on detection changes
  performance:
    max_files: 50              # Split commits if > N files
    timeout_test: 300          # Test timeout in seconds
  file_validation:
    max_file_size_mb: 10       # File size limit (default: 10MB)
    block_large_files: true    # Block large files or just warn
    detect_api_tokens: true    # Scan for API tokens
    auto_manage_gitignore: true  # Auto-update .gitignore
    auto_add_dot_folders: true   # Auto-add dot folders to .gitignore
    known_dot_folders:         # Custom dot folders to ignore
      - .idea
      - .vscode
      - .DS_Store
      - .pytest_cache
      - .code2llm_cache
      - .llm
    token_patterns: []         # Custom regex patterns for token detection

Config Commands

# Show full configuration
goal config show

# Show specific key (dot notation)
goal config show -k git.commit.strategy

# Get a value
goal config get project.name

# Set a value
goal config set git.commit.scope "my-app"

# Validate configuration
goal config validate

# Update config based on project detection
goal config update

Custom Config File

# Use a custom config file
goal --config custom-goal.yaml push

# Or in CI/CD
goal -c .goal/ci.yaml --all

Conventions (without goal.yaml)

Goal also works without configuration based on conventions:

1. Version detection: Looks for VERSION file first, then project-specific files
2. Project detection: Automatically detects project type from files
3. Commit messages: Uses conventional commit format based on diff analysis
4. Changelog: Updates CHANGELOG.md in Keep a Changelog format

Integration Examples

Makefile

.PHONY: release patch minor major

# Interactive release
release:
	goal

# Automatic patch release
patch:
	goal push --yes

# Full automation release
all:
	goal --all

# Automatic minor release
minor:
	goal push --yes --bump minor

# Automatic major release
major:
	goal push --yes --bump major

# Dry run
dry-run:
	goal push --dry-run

# Release with custom message
release-message:
	goal push --yes -m "$(MSG)"

# Release from specific branch
release-branch:
	git checkout main
	git pull
	goal --all --bump $(BUMP)

package.json scripts

{
  "scripts": {
    "release": "goal",
    "release:patch": "goal push --yes",
    "release:all": "goal --all",
    "release:minor": "goal push --yes --bump minor",
    "release:major": "goal push --yes --bump major",
    "release:dry": "goal push --dry-run",
    "release:docs": "goal push --yes -m 'docs: update documentation'"
  }
}

pre-commit hook

#!/bin/sh
# .git/hooks/pre-commit
echo "Running goal pre-commit check..."
goal push --dry-run
if [ $? -eq 0 ]; then
    echo "✅ Ready to commit!"
else
    echo "❌ Issues found. Fix them before committing."
    exit 1
fi

Docker integration

# Dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install -r requirements.txt

# Install goal
RUN pip install goal

# Copy source code
COPY . .

# Run tests and release
CMD ["sh", "-c", "goal --all"]

Smart Commit Messages

Goal analyzes your changes to generate appropriate commit messages:

• feat: New features, additions
• fix: Bug fixes, patches
• docs: Documentation changes
• style: Formatting, linting
• refactor: Code restructuring
• perf: Performance improvements
• test: Test additions/changes
• build: Build system, CI/CD
• chore: Dependencies, maintenance

Examples:

• feat: add user authentication
• fix: resolve memory leak in parser
• docs: update API documentation
• test: add coverage for payment module

Troubleshooting

Security Validation Blocks Commit

Goal automatically protects against security issues:

# Large file detected
❌ Validation Error: File database.dump is 15.2MB, which exceeds the limit of 10MB

# API token detected  
❌ Validation Error: Potential GitHub Personal Access token detected in .env:5

# Solutions:
1. Remove the sensitive/large file
2. Add the file to .gitignore
3. Use --force to bypass (not recommended)

Configure Security Validation

# goal.yaml
advanced:
  file_validation:
    max_file_size_mb: 10        # Adjust limit
    block_large_files: false    # Only warn instead of block
    detect_api_tokens: true     # Enable/disable token detection
    auto_manage_gitignore: false # Disable auto .gitignore updates

Tests fail but I want to continue

The interactive workflow will ask if you want to continue when tests fail:

Tests failed. Continue anyway? [y/N]

Custom test/publish commands

If Goal doesn't detect your test command correctly, you can run them manually before using goal push --yes.

TODO Management

Goal can automatically add detected issues to TODO.md without duplicates:

# Diagnose and add unfixed issues to TODO.md
goal doctor --todo
goal doctor -t

# Diagnose without auto-fix but add to TODO.md
goal doctor --todo --no-fix
goal doctor -t --no-fix

# Full workflow with TODO tracking
goal --all --todo
goal -a -t

Features:

• 🎫 Unique ticket IDs - Format [CODE-identifier] for each issue
• 🚫 No duplicates - Checks existing tickets before adding
• 🎨 Rich formatting - Icons, severity levels, file references
• 📅 Timestamped sections - Groups issues by detection date

Example TODO.md entry:

## Issues Found - 2026-02-24

- [PY002-missingbuildsysteminpyprojecttoml] 🔴 **Missing [build-system] in pyproject.toml** (`pyproject.toml`)
  - pyproject.toml has no [build-system] section.
  - pip and build tools need this to know how to build your package.
  - Adding a default setuptools build-system.

Publishing fails

Ensure you're authenticated with the appropriate package manager:

PyPI Authentication Options:

• Recommended: Configure ~/.pypirc file (development)
• CI/CD: Set PYPI_TOKEN environment variable
• Interactive: Run twine configure

~/.pypirc setup (recommended for development):

[pypi]
  username = __token__
  password = pypi-AgEIcHlwaS5vcmcC...

Environment variable setup (for CI/CD):

export PYPI_TOKEN=your_token_here

Other package managers:

• npm: npm login
• crates.io: cargo login

Common Issues

Goal doesn't detect my project type

# Check what's detected
goal info

# Manually specify in goal.yaml
project:
  type: ["python", "nodejs"]

Version sync not working

# Check version files
goal info

# Manually configure in goal.yaml
versioning:
  files:
    - "VERSION"
    - "my-app/__init__.py:__version__"

Tests timing out

# In goal.yaml
advanced:
  performance:
    timeout_test: 600  # 10 minutes

Commit message not accurate

# Use custom message
goal push -m "your custom message"

# Or configure templates in goal.yaml
git:
  commit:
    templates:
      feat: "feat({scope}): {description}"

User Configuration

Goal automatically manages your project metadata using your git configuration and license preferences.

First-time Setup

On first run, Goal will:

1. Auto-detect your git user.name and user.email
2. Ask for license preference (8 popular open source licenses)
3. Save to ~/.goal for future use

$ goal

======================================================================
  🎯 Goal - First Time Setup
======================================================================

✓ Detected git user.name: Tom Sapletta
✓ Detected git user.email: [e-mail]

======================================================================
  📄 License Selection
======================================================================

  1. Apache License 2.0
  2. MIT License
  3. GNU General Public License v3.0
  4. BSD 3-Clause License
  5. GNU General Public License v2.0
  6. GNU Lesser General Public License v3.0
  7. GNU Affero General Public License v3.0
  8. Mozilla Public License 2.0

Enter your choice [1]: 1

✓ Configuration saved to ~/.goal

What Gets Updated Automatically

Every time you run goal, it updates:

Project Files:

• pyproject.toml - authors, license, classifier
• package.json - author, license, contributors
• Cargo.toml - authors, license
• VERSION - version number
• __init__.py - __version__ variable (in all packages)

README.md:

• License badges (Apache-2.0, MIT, GPL, etc.)
• ## License section
• ## Author section

Smart Author Management

Goal adds authors instead of replacing them:

# Before (existing author)
authors = [{name = "Original Author", email = "[e-mail]"}]

# After (Goal adds you)
authors = [
    {name = "Original Author", email = "[e-mail]"},
    {name = "Tom Sapletta", email = "[e-mail]"},
]

Managing Your Configuration

# View current configuration
goal config

# Reset and reconfigure
goal config --reset

# Configuration file location
~/.goal

Example Output

$ goal config

======================================================================
  📋 Goal User Configuration
======================================================================

Config file: /home/tom/.goal

Current settings:
  Author name:  Tom Sapletta
  Author email: [e-mail]
  License:      Apache License 2.0 (Apache-2.0)

💡 Tip: Run 'goal config --reset' to reconfigure

Tips & Tricks

1. Use with aliases

# Add to ~/.bashrc or ~/.zshrc
alias g='goal'
alias gp='goal push --yes'
alias ga='goal --all'
alias gd='goal push --dry-run'

2. Team workflow

# For team development, use ticket prefixes
echo "prefix=PROJ-123" > TICKET
goal push --split  # Creates commits like "PROJ-123: feat: add feature"

3. Release checklist

# Before release
goal status      # Check status
goal push --dry-run  # Preview changes

# Release
goal --all       # Full automation

4. Working with feature flags

# Commit feature flag changes
goal push -m "feat: enable beta feature flag"

# Later, remove the flag
goal push -m "feat: launch feature to all users"

5. Automated releases on schedule

# .github/workflows/scheduled-release.yml
name: Scheduled Release
on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9 AM
jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Goal
        run: pip install goal
      - name: Weekly Release
        run: goal --all --bump patch

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - [e-mail]

---

_{Built with ❤️ by the community}