format

Documentation

Overview

Package format handles worktree folder name generation and path sanitization.

Worktree folders are named using a configurable format string with placeholders that are substituted at creation time.

Format Placeholders

Available placeholders for worktree_format config:

• {repo}: Folder name of git repo
• {branch}: Branch name as provided to the command
• {origin}: Repository name from git origin URL (falls back to {repo})

Default format is "{repo}-{branch}", creating folders like "my-repo-feature-x".

Path Sanitization

Branch and repo names are sanitized to create valid filesystem paths. Characters replaced with "-": / \ : * ? " < > |

This ensures branches like "feature/my-branch" become "feature-my-branch" in the folder name.

Validation

Use ValidateFormat to check format strings before use. It ensures:

• All placeholders are recognized
• At least one placeholder is present (pure static names aren't useful)

Index

• Constants
• Variables
• func FormatWorktreeName(format string, params FormatParams) string
• func RelativeTime(t time.Time) string
• func RelativeTimeFrom(t, now time.Time) string
• func SanitizeForPath(name string) string
• func UniqueWorktreePath(basePath string, exists PathExistsFunc) string
• func ValidateFormat(format string) error
• type FormatParams
• type PathExistsFunc

Constants

const DefaultWorktreeFormat = "{repo}-{branch}"

DefaultWorktreeFormat is the default format for worktree folder names

Variables

var ValidPlaceholders = []string{"{repo}", "{branch}", "{origin}"}

ValidPlaceholders lists all supported placeholders

Functions

func FormatWorktreeName

func FormatWorktreeName(format string, params FormatParams) string

FormatWorktreeName applies the format template to generate a worktree folder name

func RelativeTime

func RelativeTime(t time.Time) string

RelativeTime formats a time as a human-readable relative string. Returns "Xs ago", "Xm ago", "Xh ago", "yesterday", or date for older.

func RelativeTimeFrom

func RelativeTimeFrom(t, now time.Time) string

RelativeTimeFrom formats a time relative to a reference time. Useful for testing with a fixed "now".

func SanitizeForPath

func SanitizeForPath(name string) string

SanitizeForPath replaces characters that are problematic in file paths Replaces: / \ : * ? " < > | with -

func UniqueWorktreePath

func UniqueWorktreePath(basePath string, exists PathExistsFunc) string

UniqueWorktreePath returns a unique path by appending a numbered suffix if needed. If basePath doesn't exist, it returns basePath unchanged. If basePath exists, it tries basePath-1, basePath-2, etc. until finding a unique path.

func ValidateFormat

func ValidateFormat(format string) error

ValidateFormat checks if a format string is valid Returns error if format contains unknown placeholders

Types

type FormatParams

type FormatParams struct {
	RepoName   string // folder name of git repo
	BranchName string // branch name as provided
	Origin     string // repo name from git origin URL (falls back to RepoName if empty)
}

FormatParams contains the values for placeholder substitution

type PathExistsFunc

type PathExistsFunc func(path string) bool

PathExistsFunc is a function that checks if a path exists. Used for dependency injection in tests.