Documentation
¶
Overview ¶
Package config provides repository configuration management, including reading and writing stackit configuration files.
Package config provides repository configuration management.
It handles:
- Repository-specific configuration (stored in git config)
- Migration from legacy JSON config to git config
- Continuation state for interrupted operations (like merge conflicts)
Index ¶
- Constants
- Variables
- func AllGitKeys() []string
- func ClearContinuationState(repoRoot string) error
- func GenerateConfigDocs() string
- func GenerateConfigTemplate() string
- func GenerateYAMLExample() string
- func PersistContinuationState(repoRoot string, state *ContinuationState) error
- type BranchConfig
- type BranchPattern
- type CIConfig
- type Configurer
- type ContinuationState
- type GitConfig
- func (c *GitConfig) AddApprovedHook(phase, command string) error
- func (c *GitConfig) AddSubmitAssignee(assignee string) error
- func (c *GitConfig) AddSubmitLabel(label string) error
- func (c *GitConfig) AddSubmitReviewer(reviewer string) error
- func (c *GitConfig) AddTrunk(trunk string) error
- func (c *GitConfig) AllTrunks() []string
- func (c *GitConfig) ApprovedHooks(phase string) []string
- func (c *GitConfig) BranchNamePattern() string
- func (c *GitConfig) CICommand() string
- func (c *GitConfig) CITimeout() int
- func (c *GitConfig) ClearApprovedHooks(phase string) error
- func (c *GitConfig) ClearTrunks() error
- func (c *GitConfig) CombineCICommand() string
- func (c *GitConfig) CombineCITimeout() int
- func (c *GitConfig) GetBranchPattern() BranchPattern
- func (c *GitConfig) IsHookApproved(phase, command string) bool
- func (c *GitConfig) IsInitialized() bool
- func (c *GitConfig) IsTrunk(branch string) bool
- func (c *GitConfig) MaxConcurrency() int
- func (c *GitConfig) MergeMethod() github.MergeMethod
- func (c *GitConfig) NavigationLocation() string
- func (c *GitConfig) NavigationMarker() string
- func (c *GitConfig) NavigationShowMerged() bool
- func (c *GitConfig) NavigationWhen() string
- func (c *GitConfig) ProjectConfig() *ProjectConfig
- func (c *GitConfig) RemoveApprovedHook(phase, command string) error
- func (c *GitConfig) RemoveTrunk(trunk string) error
- func (c *GitConfig) ResetAllPersonal() error
- func (c *GitConfig) Save() error
- func (c *GitConfig) SetBranchNamePattern(pattern string) error
- func (c *GitConfig) SetCICommand(cmd string) error
- func (c *GitConfig) SetCITimeout(seconds int) error
- func (c *GitConfig) SetCombineCICommand(cmd string)
- func (c *GitConfig) SetCombineCITimeout(seconds int)
- func (c *GitConfig) SetMaxConcurrency(n int) error
- func (c *GitConfig) SetMergeMethod(method github.MergeMethod) error
- func (c *GitConfig) SetNavigationLocation(location string) error
- func (c *GitConfig) SetNavigationMarker(marker string) error
- func (c *GitConfig) SetNavigationShowMerged(show bool) error
- func (c *GitConfig) SetNavigationWhen(when string) error
- func (c *GitConfig) SetSplitHunkSelector(selector string) error
- func (c *GitConfig) SetSubmitAssignees(assignees []string) error
- func (c *GitConfig) SetSubmitDraft(draft bool) error
- func (c *GitConfig) SetSubmitFooter(enabled bool) error
- func (c *GitConfig) SetSubmitLabels(labels []string) error
- func (c *GitConfig) SetSubmitReviewers(reviewers []string) error
- func (c *GitConfig) SetSubmitWeb(web string) error
- func (c *GitConfig) SetTrunk(trunk string) error
- func (c *GitConfig) SetUndoEnabled(enabled bool) error
- func (c *GitConfig) SetUndoStackDepth(depth int) error
- func (c *GitConfig) SetWorktreeAutoClean(enabled bool) error
- func (c *GitConfig) SetWorktreeBasePath(path string) error
- func (c *GitConfig) SplitHunkSelector() string
- func (c *GitConfig) SubmitAssignees() []string
- func (c *GitConfig) SubmitDraft() bool
- func (c *GitConfig) SubmitFooter() bool
- func (c *GitConfig) SubmitLabels() []string
- func (c *GitConfig) SubmitReviewers() []string
- func (c *GitConfig) SubmitWeb() string
- func (c *GitConfig) Trunk() string
- func (c *GitConfig) UndoEnabled() bool
- func (c *GitConfig) UndoStackDepth() int
- func (c *GitConfig) UnsetBranchNamePattern() error
- func (c *GitConfig) UnsetCICommand() error
- func (c *GitConfig) UnsetCITimeout() error
- func (c *GitConfig) UnsetMaxConcurrency() error
- func (c *GitConfig) UnsetMergeMethod() error
- func (c *GitConfig) UnsetNavigationLocation() error
- func (c *GitConfig) UnsetNavigationMarker() error
- func (c *GitConfig) UnsetNavigationShowMerged() error
- func (c *GitConfig) UnsetNavigationWhen() error
- func (c *GitConfig) UnsetSplitHunkSelector() error
- func (c *GitConfig) UnsetSubmitAssignees() error
- func (c *GitConfig) UnsetSubmitDraft() error
- func (c *GitConfig) UnsetSubmitFooter() error
- func (c *GitConfig) UnsetSubmitLabels() error
- func (c *GitConfig) UnsetSubmitReviewers() error
- func (c *GitConfig) UnsetSubmitWeb() error
- func (c *GitConfig) UnsetTrunk() error
- func (c *GitConfig) UnsetUndoEnabled() error
- func (c *GitConfig) UnsetUndoStackDepth() error
- func (c *GitConfig) UnsetWorktreeAutoClean() error
- func (c *GitConfig) UnsetWorktreeBasePath() error
- func (c *GitConfig) WorktreeAutoClean() bool
- func (c *GitConfig) WorktreeBasePath() string
- type GitContext
- type HooksConfig
- type MergeConfig
- type NavigationConfig
- type Option
- type ProjectConfig
- func (c *ProjectConfig) GetMaxConcurrency() int
- func (c *ProjectConfig) GetNavigationShowMerged() bool
- func (c *ProjectConfig) GetSubmitDraft() bool
- func (c *ProjectConfig) GetSubmitFooter() bool
- func (c *ProjectConfig) GetWorktreeAutoClean() bool
- func (c *ProjectConfig) HasBranchPattern() bool
- func (c *ProjectConfig) HasCICommand() bool
- func (c *ProjectConfig) HasCITimeout() bool
- func (c *ProjectConfig) HasMaxConcurrency() bool
- func (c *ProjectConfig) HasMergeMethod() bool
- func (c *ProjectConfig) HasNavigationLocation() bool
- func (c *ProjectConfig) HasNavigationMarker() bool
- func (c *ProjectConfig) HasNavigationShowMerged() bool
- func (c *ProjectConfig) HasNavigationWhen() bool
- func (c *ProjectConfig) HasPostWorktreeCreateHooks() bool
- func (c *ProjectConfig) HasSplitHunkSelector() bool
- func (c *ProjectConfig) HasSubmitAssignees() bool
- func (c *ProjectConfig) HasSubmitDraft() bool
- func (c *ProjectConfig) HasSubmitFooter() bool
- func (c *ProjectConfig) HasSubmitLabels() bool
- func (c *ProjectConfig) HasSubmitReviewers() bool
- func (c *ProjectConfig) HasSubmitWeb() bool
- func (c *ProjectConfig) HasTrunk() bool
- func (c *ProjectConfig) HasTrunks() bool
- func (c *ProjectConfig) HasUndoDepth() bool
- func (c *ProjectConfig) HasUndoEnabled() bool
- func (c *ProjectConfig) HasWorktreeAutoClean() bool
- func (c *ProjectConfig) HasWorktreeBasePath() bool
- func (c *ProjectConfig) Validate() error
- type RepoConfig
- type Section
- type SplitConfig
- type SubmitConfig
- type UndoConfig
- type WorktreeConfig
Constants ¶
const ( // KeyTrunk is the primary trunk branch name. KeyTrunk = "stackit.trunk" // KeyTrunks stores additional trunk branches (multi-value). KeyTrunks = "stackit.trunks" // KeyBranchPattern is the pattern used for generating branch names. KeyBranchPattern = "stackit.branch.pattern" KeySubmitFooter = "stackit.submit.footer" // KeyUndoDepth is the maximum number of undo snapshots to keep. KeyUndoDepth = "stackit.undo.depth" // KeyUndoEnabled controls whether undo snapshots are taken at all. // Set to false to skip snapshot overhead for users who never run `stackit undo`. KeyUndoEnabled = "stackit.undo.enabled" // KeyWorktreeBasePath is the base path for worktrees. KeyWorktreeBasePath = "stackit.worktree.basePath" // KeyWorktreeAutoClean controls automatic worktree cleanup during sync. KeyWorktreeAutoClean = "stackit.worktree.autoClean" // KeyMergeMethod is the preferred merge method (squash, merge, rebase). KeyMergeMethod = "stackit.merge.method" // KeyCICommand is the unified CI validation command. KeyCICommand = "stackit.ci.command" // KeyCITimeout is the CI command timeout in seconds. KeyCITimeout = "stackit.ci.timeout" // KeySplitHunkSelector is the hunk selector mode for split (tui or git). KeySplitHunkSelector = "stackit.split.hunkSelector" // KeyApprovedHooks stores approved post-worktree-create hooks (multi-value). // // Deprecated: kept as a compat read-path. New approvals are written under // the per-phase family KeyApprovedHookPrefix+<phase>. KeyApprovedHooks = "stackit.hooks.approvedPostWorktreeCreate" // KeyApprovedHookPrefix is the prefix for per-phase hook approval keys. // Full key form: <prefix><phase>, e.g. "stackit.hooks.approved.pre-modify". KeyApprovedHookPrefix = "stackit.hooks.approved." // KeyMaxConcurrency is the maximum number of concurrent validation operations. KeyMaxConcurrency = "stackit.maxConcurrency" KeyNavigationWhen = "stackit.navigation.when" KeyNavigationMarker = "stackit.navigation.marker" KeyNavigationLocation = "stackit.navigation.location" KeyNavigationShowMerged = "stackit.navigation.showMerged" // KeySubmitDraft controls whether to create PRs as drafts by default. KeySubmitDraft = "stackit.submit.draft" // KeySubmitWeb controls when to open PRs in browser (always/created/never). KeySubmitWeb = "stackit.submit.web" // KeySubmitLabels stores default labels for PRs (multi-value). KeySubmitLabels = "stackit.submit.labels" // KeySubmitReviewers stores default reviewers for PRs (multi-value). KeySubmitReviewers = "stackit.submit.reviewers" // KeySubmitAssignees stores default assignees for PRs (multi-value). KeySubmitAssignees = "stackit.submit.assignees" )
Git config keys for stackit configuration. All keys are prefixed with "stackit." to namespace them within git config.
const ( YAMLPathTrunk = "trunk" YAMLPathTrunks = "trunks" YAMLPathBranchPattern = "branch.pattern" YAMLPathSubmitDraft = "submit.draft" YAMLPathSubmitWeb = "submit.web" YAMLPathSubmitLabels = "submit.labels" YAMLPathSubmitReviewers = "submit.reviewers" YAMLPathSubmitAssignees = "submit.assignees" YAMLPathMergeMethod = "merge.method" YAMLPathCICommand = "ci.command" YAMLPathCITimeout = "ci.timeout" YAMLPathUndoDepth = "undo.depth" YAMLPathUndoEnabled = "undo.enabled" YAMLPathWorktreeBasePath = "worktree.basePath" YAMLPathWorktreeAutoClean = "worktree.autoClean" YAMLPathSplitHunkSelector = "split.hunkSelector" YAMLPathMaxConcurrency = "maxConcurrency" YAMLPathHooksPostWorktree = "hooks.post-worktree-create" )
YAML path constants for configuration options. These are the paths used in .stackit.yaml files.
const ( // DefaultTrunk is the default trunk branch name. DefaultTrunk = "main" DefaultSubmitFooter = true // DefaultUndoDepth is the default number of undo snapshots to keep. DefaultUndoDepth = 10 // DefaultUndoEnabled is whether undo snapshots are taken by default. DefaultUndoEnabled = true // DefaultWorktreeAutoClean is whether to auto-clean worktrees by default. DefaultWorktreeAutoClean = true // DefaultCITimeout is the default CI timeout in seconds (10 minutes). DefaultCITimeout = 600 // DefaultSplitHunkSelector is the default hunk selector mode. DefaultSplitHunkSelector = "tui" // DefaultMaxConcurrency is the default max concurrent operations (0 = auto). DefaultMaxConcurrency = 0 DefaultNavigationWhen = "multiple" DefaultNavigationMarker = "👈" DefaultNavigationLocation = "body" DefaultNavigationShowMerged = true // DefaultSubmitDraft is whether to create PRs as drafts by default. DefaultSubmitDraft = false // DefaultSubmitWeb is when to open PRs in browser by default. DefaultSubmitWeb = "never" )
Default values for configuration.
const ( SectionTrunk = "trunk" SectionTrunks = "trunks" // array variant of trunk for YAML and validation SectionBranch = "branch" SectionSubmit = "submit" SectionMerge = "merge" SectionCI = "ci" SectionUndo = "undo" SectionWorktree = "worktree" SectionSplit = "split" SectionConcurrency = "concurrency" SectionHooks = "hooks" )
Config section name constants. These identify configuration sections used in the metadata registry, YAML validation, and documentation generation.
const ( )
Navigation when constants (valid values for KeyNavigationWhen).
const ( )
Navigation location constants.
const ( SubmitWebAlways = "always" SubmitWebCreated = "created" SubmitWebNever = "never" )
Submit web constants.
const (
PhasePostWorktreeCreate = "post-worktree-create"
)
Hook phase identifiers. These are the suffix used after KeyApprovedHookPrefix and as the YAML key under .stackit.yaml's `hooks:` block.
const ProjectConfigFileName = ".stackit.yaml"
ProjectConfigFileName is the name of the project configuration file
Variables ¶
var Options = []Option{ { YAMLPath: YAMLPathTrunk, GitKey: KeyTrunk, Description: "Primary trunk branch", Default: DefaultTrunk, Section: SectionTrunk, }, { YAMLPath: YAMLPathTrunks, GitKey: KeyTrunks, Description: "Additional trunk branches (e.g., release branches)", IsArray: true, Example: "develop, release", Section: SectionTrunk, }, { YAMLPath: YAMLPathBranchPattern, GitKey: KeyBranchPattern, Description: "Branch naming pattern", Comment: "Placeholders: {username}, {date}, {message}, {scope}", Example: "{username}/{date}/{message}", Section: SectionBranch, }, { YAMLPath: YAMLPathSubmitFooter, GitKey: KeySubmitFooter, Description: "Include navigation footer", Default: DefaultSubmitFooter, Section: SectionSubmit, }, { YAMLPath: YAMLPathSubmitDraft, GitKey: KeySubmitDraft, Description: "Create as draft", Default: DefaultSubmitDraft, Section: SectionSubmit, }, { YAMLPath: YAMLPathSubmitWeb, GitKey: KeySubmitWeb, Description: "Open in browser: always, created, never", Default: DefaultSubmitWeb, ValidValues: ValidSubmitWeb, Section: SectionSubmit, }, { YAMLPath: YAMLPathSubmitLabels, GitKey: KeySubmitLabels, Description: "Default labels", IsArray: true, Section: SectionSubmit, }, { YAMLPath: YAMLPathSubmitReviewers, GitKey: KeySubmitReviewers, Description: "Default reviewers", IsArray: true, Section: SectionSubmit, }, { YAMLPath: YAMLPathSubmitAssignees, GitKey: KeySubmitAssignees, Description: "Default assignees", IsArray: true, Section: SectionSubmit, }, { YAMLPath: YAMLPathMergeMethod, GitKey: KeyMergeMethod, Description: "Merge method: squash, merge, rebase", ValidValues: ValidMergeMethods, Example: string(github.MergeMethodSquash), Section: SectionMerge, }, { YAMLPath: YAMLPathCICommand, GitKey: KeyCICommand, Description: "Command to run", Example: ciCommandExample, Section: SectionCI, }, { YAMLPath: YAMLPathCITimeout, GitKey: KeyCITimeout, Description: "Timeout in seconds", Default: DefaultCITimeout, Section: SectionCI, }, { YAMLPath: YAMLPathUndoDepth, GitKey: KeyUndoDepth, Description: "Max snapshots", Default: DefaultUndoDepth, Section: SectionUndo, }, { YAMLPath: YAMLPathUndoEnabled, GitKey: KeyUndoEnabled, Description: "Take snapshots before mutations (set false to skip undo overhead)", Default: DefaultUndoEnabled, Section: SectionUndo, }, { YAMLPath: YAMLPathWorktreeBasePath, GitKey: KeyWorktreeBasePath, Description: "Base directory (empty = auto)", Example: "", Section: SectionWorktree, }, { YAMLPath: YAMLPathWorktreeAutoClean, GitKey: KeyWorktreeAutoClean, Description: "Clean during sync", Default: DefaultWorktreeAutoClean, Section: SectionWorktree, }, { YAMLPath: YAMLPathSplitHunkSelector, GitKey: KeySplitHunkSelector, Description: "tui or git", Default: DefaultSplitHunkSelector, ValidValues: ValidHunkSelectors, Section: SectionSplit, }, { YAMLPath: YAMLPathMaxConcurrency, GitKey: KeyMaxConcurrency, Description: "0 = auto-detect", Default: DefaultMaxConcurrency, Section: SectionConcurrency, }, { YAMLPath: YAMLPathNavigationWhen, GitKey: KeyNavigationWhen, Description: "always, never, multiple", Default: DefaultNavigationWhen, ValidValues: ValidNavigationWhen, Section: SectionNavigation, }, { YAMLPath: YAMLPathNavigationLocation, GitKey: KeyNavigationLocation, Description: "body, comment, none", Default: DefaultNavigationLocation, ValidValues: ValidNavigationLocation, Section: SectionNavigation, }, { YAMLPath: YAMLPathNavigationMarker, GitKey: KeyNavigationMarker, Description: "Current branch marker", Default: DefaultNavigationMarker, Section: SectionNavigation, }, { YAMLPath: YAMLPathNavigationShowMerged, GitKey: KeyNavigationShowMerged, Description: "Show merged history", Default: DefaultNavigationShowMerged, Section: SectionNavigation, }, { YAMLPath: YAMLPathHooksPostWorktree, GitKey: KeyApprovedHooks, Description: "Commands to run after creating a worktree", IsArray: true, Example: "npm install, mise install", Section: SectionHooks, }, }
Options is the registry of all configuration options. This is the single source of truth for all config keys and their metadata.
var Sections = []Section{ {Name: SectionTrunk, Title: "", DocsTitle: "Trunk branches"}, {Name: SectionBranch, Title: "Branch naming pattern", DocsTitle: "Branch naming"}, {Name: SectionSubmit, Title: "PR submission settings", DocsTitle: "PR submission"}, {Name: SectionMerge, Title: "Merge method: squash, merge, rebase", DocsTitle: "Merge settings"}, {Name: SectionCI, Title: "CI validation", DocsTitle: "CI validation"}, {Name: SectionUndo, Title: "Undo history", DocsTitle: "Other settings"}, {Name: SectionWorktree, Title: "Worktree settings", DocsTitle: "Worktree settings"}, {Name: SectionSplit, Title: "Split command", DocsTitle: "Split command"}, {Name: SectionConcurrency, Title: "Concurrency", DocsTitle: ""}, {Name: SectionNavigation, Title: "PR navigation display", DocsTitle: "PR navigation"}, {Name: SectionHooks, Title: "Post-worktree-create hooks (require approval on first run)", DocsTitle: ""}, }
Sections defines the ordering and titles for config sections. This is the single source of truth for section organization.
var ValidHunkSelectors = []string{"tui", "git"}
ValidHunkSelectors contains the allowed hunk selector values.
var ValidMergeMethods = []string{ string(github.MergeMethodSquash), string(github.MergeMethodMerge), string(github.MergeMethodRebase), }
ValidMergeMethods contains the allowed merge method values (the string names of github.ValidMergeMethods, for config metadata and error messages).
ValidNavigationLocation contains the allowed navigation location values. "none" is an alias for disabling navigation (equivalent to when=never).
ValidNavigationWhen contains the allowed navigation when values.
var ValidSubmitWeb = []string{SubmitWebAlways, SubmitWebCreated, SubmitWebNever}
ValidSubmitWeb contains the allowed submit.web values.
Functions ¶
func AllGitKeys ¶
func AllGitKeys() []string
AllGitKeys returns all git config keys from the registry.
func ClearContinuationState ¶
ClearContinuationState removes the continuation state file
func GenerateConfigDocs ¶
func GenerateConfigDocs() string
GenerateConfigDocs generates markdown documentation for all configuration options. This is used to generate the config reference documentation.
func GenerateConfigTemplate ¶
func GenerateConfigTemplate() string
GenerateConfigTemplate generates a .stackit.yaml template with all options commented out. The template is generated from Options, ensuring it stays in sync with the codebase.
func GenerateYAMLExample ¶
func GenerateYAMLExample() string
GenerateYAMLExample generates an example .stackit.yaml with common settings uncommented. This is used in documentation to show a complete working example.
func PersistContinuationState ¶
func PersistContinuationState(repoRoot string, state *ContinuationState) error
PersistContinuationState writes the continuation state to disk
Types ¶
type BranchConfig ¶
type BranchConfig struct {
Pattern string `yaml:"pattern,omitempty"`
}
BranchConfig contains branch naming configuration
type BranchPattern ¶
type BranchPattern string
BranchPattern represents a branch name pattern with validation
const DefaultBranchPattern BranchPattern = "{username}/{date}/{message}"
DefaultBranchPattern is the default branch name pattern
func NewBranchPattern ¶
func NewBranchPattern(pattern string) (BranchPattern, error)
NewBranchPattern creates a new BranchPattern from a string Returns an error if the pattern is invalid (doesn't contain {message})
func (BranchPattern) ContainsScope ¶
func (p BranchPattern) ContainsScope() bool
ContainsScope returns true if the pattern contains the {scope} placeholder
func (BranchPattern) GetBranchName ¶
func (p BranchPattern) GetBranchName(ctx GitContext, commitMessage string, scope string) (string, error)
GetBranchName generates a branch name from the pattern using the provided commit message and optional scope. It fetches the username and current date internally only if needed by the pattern.
func (BranchPattern) IsValid ¶
func (p BranchPattern) IsValid() bool
IsValid checks if the pattern is valid (contains {message})
func (BranchPattern) String ¶
func (p BranchPattern) String() string
String returns the string representation of the pattern
func (BranchPattern) WithDefault ¶
func (p BranchPattern) WithDefault() BranchPattern
WithDefault returns the pattern, or the default if empty
type CIConfig ¶
type CIConfig struct {
Command string `yaml:"command,omitempty"`
Timeout int `yaml:"timeout,omitempty"`
}
CIConfig contains CI validation configuration
type Configurer ¶
type Configurer interface {
// Initialization
IsInitialized() bool
// Trunk configuration
Trunk() string
AllTrunks() []string
IsTrunk(branch string) bool
// Branch naming
BranchNamePattern() string
GetBranchPattern() BranchPattern
SubmitFooter() bool
// Undo settings
UndoStackDepth() int
UndoEnabled() bool
// Worktree settings
WorktreeBasePath() string
WorktreeAutoClean() bool
// Merge settings
MergeMethod() github.MergeMethod
// CI settings
CICommand() string
CITimeout() int
// Split settings
SplitHunkSelector() string
// Concurrency settings
MaxConcurrency() int
// Navigation settings
// Project config access (.stackit.yaml). Returns nil if unloaded.
ProjectConfig() *ProjectConfig
// Hook approvals
ApprovedHooks(phase string) []string
IsHookApproved(phase, command string) bool
AddApprovedHook(phase, command string) error
// Deprecated methods (for backwards compatibility)
CombineCICommand() string
CombineCITimeout() int
}
Configurer is the interface for stackit configuration. The git-based GitConfig implements this interface.
type ContinuationState ¶
type ContinuationState struct {
BranchesToRestack []string `json:"branchesToRestack,omitempty"`
BranchesToSync []string `json:"branchesToSync,omitempty"` // For future sync command
CurrentBranchOverride string `json:"currentBranchOverride,omitempty"`
RebasedBranchBase string `json:"rebasedBranchBase,omitempty"`
}
ContinuationState represents the state of a command that was interrupted by a rebase conflict
func GetContinuationState ¶
func GetContinuationState(repoRoot string) (*ContinuationState, error)
GetContinuationState reads the continuation state from disk
type GitConfig ¶
type GitConfig struct {
// contains filtered or unexported fields
}
GitConfig provides typed access to stackit configuration stored in git config. This replaces the JSON-based config storage with native git config. Configuration follows a layered system: personal git config > team project config > defaults.
func LoadConfig ¶
LoadConfig loads the repository configuration. This function delegates to LoadGitConfigWithProject for git-based config storage with project config (.stackit.yaml) fallback support. It automatically migrates any existing JSON config to git config.
func LoadGitConfig ¶
LoadGitConfig loads configuration from git config. If JSON config exists and needs migration, it will be migrated automatically. This function does NOT load project config (.stackit.yaml) - use LoadGitConfigWithProject for that.
func LoadGitConfigWithProject ¶
LoadGitConfigWithProject loads configuration from git config with project config fallback. The layered system follows: personal git config > team project config (.stackit.yaml) > defaults.
func (*GitConfig) AddApprovedHook ¶ added in v0.19.0
AddApprovedHook records an approval for the given phase. Approvals are written to the per-phase key; the legacy key is read but never written.
func (*GitConfig) AddSubmitAssignee ¶
AddSubmitAssignee adds an assignee to the default assignees.
func (*GitConfig) AddSubmitLabel ¶
AddSubmitLabel adds a label to the default labels.
func (*GitConfig) AddSubmitReviewer ¶
AddSubmitReviewer adds a reviewer to the default reviewers.
func (*GitConfig) AllTrunks ¶
AllTrunks returns all configured trunk branches (primary + additional). Merges trunks from git config and project config (deduplicated).
func (*GitConfig) ApprovedHooks ¶ added in v0.19.0
ApprovedHooks returns the list of approved hook commands for the given phase.
For PhasePostWorktreeCreate, results include any approvals stored under the legacy single-key form (KeyApprovedHooks) in addition to the new per-phase key. Approvals appearing in both keys are deduplicated.
func (*GitConfig) BranchNamePattern ¶
BranchNamePattern returns the branch name pattern. Priority: personal git config > team project config > default.
func (*GitConfig) CICommand ¶
CICommand returns the CI validation command. Priority: personal git config > team project config > empty (not set).
func (*GitConfig) CITimeout ¶
CITimeout returns the CI timeout in seconds. Priority: personal git config > team project config > default.
func (*GitConfig) ClearApprovedHooks ¶ added in v0.19.0
ClearApprovedHooks removes all approvals for the given phase. For PhasePostWorktreeCreate, this also clears the legacy key.
func (*GitConfig) ClearTrunks ¶
ClearTrunks removes all additional trunks from personal git config. Note: Trunks from team config (.stackit.yaml) will still be visible in AllTrunks().
func (*GitConfig) CombineCICommand ¶
CombineCICommand returns the CI command (deprecated, use CICommand).
func (*GitConfig) CombineCITimeout ¶
CombineCITimeout returns the CI timeout (deprecated, use CITimeout).
func (*GitConfig) GetBranchPattern ¶
func (c *GitConfig) GetBranchPattern() BranchPattern
GetBranchPattern returns the branch pattern object.
func (*GitConfig) IsHookApproved ¶ added in v0.19.0
IsHookApproved reports whether the command is approved for the given phase.
func (*GitConfig) IsInitialized ¶
IsInitialized checks if stackit has been initialized (trunk is set).
func (*GitConfig) MaxConcurrency ¶
MaxConcurrency returns the maximum number of concurrent validation operations. Priority: personal git config > team project config > default (0 = auto based on CPU count).
func (*GitConfig) MergeMethod ¶
func (c *GitConfig) MergeMethod() github.MergeMethod
MergeMethod returns the configured merge method (empty if not set). Priority: personal git config > team project config > empty (not set).
func (*GitConfig) NavigationLocation ¶
NavigationLocation returns where navigation should appear. Priority: personal git config > team project config > default.
func (*GitConfig) NavigationMarker ¶
NavigationMarker returns the marker symbol for the current branch. Priority: personal git config > team project config > default.
func (*GitConfig) NavigationShowMerged ¶
NavigationShowMerged returns whether to show merged branch history. Priority: personal git config > team project config > default.
func (*GitConfig) NavigationWhen ¶
NavigationWhen returns when navigation should be displayed. Priority: personal git config > team project config > default.
func (*GitConfig) ProjectConfig ¶ added in v0.19.0
func (c *GitConfig) ProjectConfig() *ProjectConfig
ProjectConfig returns the loaded project config (.stackit.yaml) attached to this GitConfig, or nil if this instance was loaded without project fallback. Callers must not mutate the returned value.
func (*GitConfig) RemoveApprovedHook ¶ added in v0.19.0
RemoveApprovedHook removes the approval for the given phase. For PhasePostWorktreeCreate, the command is removed from both the per-phase key and the legacy key if present in either.
func (*GitConfig) RemoveTrunk ¶
RemoveTrunk removes a trunk from the additional trunks list. Cannot remove the primary trunk (use SetTrunk to change it).
func (*GitConfig) ResetAllPersonal ¶
ResetAllPersonal removes all personal configuration overrides, reverting to team/default values. This clears all stackit.* keys from the local git config.
func (*GitConfig) Save ¶
Save is a no-op for GitConfig since git config writes are immediate. This method exists for API compatibility with the old Config type.
func (*GitConfig) SetBranchNamePattern ¶
SetBranchNamePattern sets the branch name pattern.
func (*GitConfig) SetCICommand ¶
SetCICommand sets the CI validation command.
func (*GitConfig) SetCITimeout ¶
SetCITimeout sets the CI timeout in seconds. Must be at least 1 second. To revert to the default timeout, use UnsetCITimeout() instead of setting to 0.
func (*GitConfig) SetCombineCICommand ¶
SetCombineCICommand sets the CI command (deprecated, use SetCICommand).
func (*GitConfig) SetCombineCITimeout ¶
SetCombineCITimeout sets the CI timeout (deprecated, use SetCITimeout).
func (*GitConfig) SetMaxConcurrency ¶
SetMaxConcurrency sets the maximum number of concurrent validation operations.
func (*GitConfig) SetMergeMethod ¶
func (c *GitConfig) SetMergeMethod(method github.MergeMethod) error
SetMergeMethod sets the merge method preference.
func (*GitConfig) SetNavigationLocation ¶
SetNavigationLocation sets where navigation should appear.
func (*GitConfig) SetNavigationMarker ¶
SetNavigationMarker sets the marker symbol for the current branch.
func (*GitConfig) SetNavigationShowMerged ¶
SetNavigationShowMerged sets whether to show merged branch history.
func (*GitConfig) SetNavigationWhen ¶
SetNavigationWhen sets when navigation should be displayed.
func (*GitConfig) SetSplitHunkSelector ¶
SetSplitHunkSelector sets the hunk selector mode.
func (*GitConfig) SetSubmitAssignees ¶
SetSubmitAssignees sets the default assignees for PRs. This replaces all existing assignees.
func (*GitConfig) SetSubmitDraft ¶
SetSubmitDraft sets whether to create PRs as drafts by default.
func (*GitConfig) SetSubmitFooter ¶
SetSubmitFooter sets whether to include PR footer.
func (*GitConfig) SetSubmitLabels ¶
SetSubmitLabels sets the default labels for PRs. This replaces all existing labels.
func (*GitConfig) SetSubmitReviewers ¶
SetSubmitReviewers sets the default reviewers for PRs. This replaces all existing reviewers.
func (*GitConfig) SetSubmitWeb ¶
SetSubmitWeb sets when to open PRs in browser.
func (*GitConfig) SetUndoEnabled ¶ added in v0.19.0
SetUndoEnabled sets whether undo snapshots are taken before mutations.
func (*GitConfig) SetUndoStackDepth ¶
SetUndoStackDepth sets the max undo depth.
func (*GitConfig) SetWorktreeAutoClean ¶
SetWorktreeAutoClean sets whether to auto-clean worktrees.
func (*GitConfig) SetWorktreeBasePath ¶
SetWorktreeBasePath sets the worktree base path.
func (*GitConfig) SplitHunkSelector ¶
SplitHunkSelector returns the hunk selector mode. Priority: personal git config > team project config > default.
func (*GitConfig) SubmitAssignees ¶
SubmitAssignees returns the default assignees for PRs. Merges assignees from git config and project config (deduplicated).
func (*GitConfig) SubmitDraft ¶
SubmitDraft returns whether to create PRs as drafts by default. Priority: personal git config > team project config > default.
func (*GitConfig) SubmitFooter ¶
SubmitFooter returns whether to include PR footer. Priority: personal git config > team project config > default.
func (*GitConfig) SubmitLabels ¶
SubmitLabels returns the default labels for PRs. Merges labels from git config and project config (deduplicated).
func (*GitConfig) SubmitReviewers ¶
SubmitReviewers returns the default reviewers for PRs. Merges reviewers from git config and project config (deduplicated).
func (*GitConfig) SubmitWeb ¶
SubmitWeb returns when to open PRs in browser. Priority: personal git config > team project config > default.
func (*GitConfig) Trunk ¶
Trunk returns the primary trunk branch name. Priority: personal git config > team project config > default.
func (*GitConfig) UndoEnabled ¶ added in v0.19.0
UndoEnabled reports whether undo snapshots should be taken. When false, TakeBestEffortSnapshot is a no-op, eliminating snapshot overhead for users who never run `stackit undo`.
func (*GitConfig) UndoStackDepth ¶
UndoStackDepth returns the max undo depth. Priority: personal git config > team project config > default.
func (*GitConfig) UnsetBranchNamePattern ¶
UnsetBranchNamePattern removes the personal branch name pattern, reverting to project/default.
func (*GitConfig) UnsetCICommand ¶
UnsetCICommand removes the personal CI command setting, reverting to project/default.
func (*GitConfig) UnsetCITimeout ¶
UnsetCITimeout removes the personal CI timeout setting, reverting to project/default.
func (*GitConfig) UnsetMaxConcurrency ¶
UnsetMaxConcurrency removes the personal max concurrency setting, reverting to default.
func (*GitConfig) UnsetMergeMethod ¶
UnsetMergeMethod removes the personal merge method setting, reverting to project/default.
func (*GitConfig) UnsetNavigationLocation ¶
UnsetNavigationLocation removes the personal navigation.location setting, reverting to project/default.
func (*GitConfig) UnsetNavigationMarker ¶
UnsetNavigationMarker removes the personal navigation.marker setting, reverting to project/default.
func (*GitConfig) UnsetNavigationShowMerged ¶
UnsetNavigationShowMerged removes the personal navigation.showMerged setting, reverting to project/default.
func (*GitConfig) UnsetNavigationWhen ¶
UnsetNavigationWhen removes the personal navigation.when setting, reverting to project/default.
func (*GitConfig) UnsetSplitHunkSelector ¶
UnsetSplitHunkSelector removes the personal split hunk selector setting, reverting to project/default.
func (*GitConfig) UnsetSubmitAssignees ¶
UnsetSubmitAssignees removes all personal submit.assignees, reverting to project/default.
func (*GitConfig) UnsetSubmitDraft ¶
UnsetSubmitDraft removes the personal submit.draft setting, reverting to project/default.
func (*GitConfig) UnsetSubmitFooter ¶
UnsetSubmitFooter removes the personal submit footer setting, reverting to project/default.
func (*GitConfig) UnsetSubmitLabels ¶
UnsetSubmitLabels removes all personal submit.labels, reverting to project/default.
func (*GitConfig) UnsetSubmitReviewers ¶
UnsetSubmitReviewers removes all personal submit.reviewers, reverting to project/default.
func (*GitConfig) UnsetSubmitWeb ¶
UnsetSubmitWeb removes the personal submit.web setting, reverting to project/default.
func (*GitConfig) UnsetTrunk ¶
UnsetTrunk removes the personal trunk setting, reverting to project/default. Note: This only makes sense if there's a project config with a trunk set, otherwise the effective trunk will be the built-in default ("main").
func (*GitConfig) UnsetUndoEnabled ¶ added in v0.19.0
UnsetUndoEnabled removes the personal undo enabled setting, reverting to project/default.
func (*GitConfig) UnsetUndoStackDepth ¶
UnsetUndoStackDepth removes the personal undo stack depth setting, reverting to project/default.
func (*GitConfig) UnsetWorktreeAutoClean ¶
UnsetWorktreeAutoClean removes the personal worktree auto clean setting, reverting to project/default.
func (*GitConfig) UnsetWorktreeBasePath ¶
UnsetWorktreeBasePath removes the personal worktree base path setting, reverting to project/default.
func (*GitConfig) WorktreeAutoClean ¶
WorktreeAutoClean returns whether to auto-clean worktrees. Priority: personal git config > team project config > default.
func (*GitConfig) WorktreeBasePath ¶
WorktreeBasePath returns the worktree base path. Priority: personal git config > team project config > empty (not set).
type GitContext ¶
GitContext is a minimal interface that provides the git user name and a context. This matches app.Context but avoids a circular dependency and keeps branch-name generation from depending on the full git runner.
type HooksConfig ¶
HooksConfig contains hook configurations keyed by lifecycle phase. Keys are phase names like "pre-modify" or "post-worktree-create"; values are shell command lists.
func (HooksConfig) For ¶ added in v0.19.0
func (h HooksConfig) For(phase string) []string
For returns the hook command list configured for the given phase. Returns nil for an unknown phase.
type MergeConfig ¶
type MergeConfig struct {
Method string `yaml:"method,omitempty"`
}
MergeConfig contains merge method configuration
type NavigationConfig ¶
type NavigationConfig struct {
}
NavigationConfig contains PR navigation display settings
type Option ¶
type Option struct {
// YAMLPath is the path in the YAML config file (e.g., "submit.footer")
YAMLPath string
// GitKey is the full git config key (e.g., "stackit.submit.footer")
GitKey string
// Description is a human-readable description of the option
Description string
// Default is the default value (nil if no default)
Default any
// ValidValues lists allowed values for enum-type options (nil if any value allowed)
ValidValues []string
// Example is an example value for the template (optional, used when Default is nil)
Example string
// IsArray indicates this is a multi-value option
IsArray bool
// Section groups related options together in the generated template
Section string
// Comment provides additional context in the template (e.g., "Placeholders: {username}, {date}")
Comment string
}
Option describes a single configuration option for documentation and template generation.
func GetOptionByGitKey ¶
GetOptionByGitKey returns the Option for a given git key, or nil if not found.
func GetOptionByYAMLPath ¶
GetOptionByYAMLPath returns the Option for a given YAML path, or nil if not found.
func GetOptionsForSection ¶
GetOptionsForSection returns all options belonging to the given section.
type ProjectConfig ¶
type ProjectConfig struct {
Trunk string `yaml:"trunk,omitempty"`
Trunks []string `yaml:"trunks,omitempty"`
Branch BranchConfig `yaml:"branch,omitempty"`
Submit SubmitConfig `yaml:"submit,omitempty"`
Merge MergeConfig `yaml:"merge,omitempty"`
CI CIConfig `yaml:"ci,omitempty"`
Undo UndoConfig `yaml:"undo,omitempty"`
Worktree WorktreeConfig `yaml:"worktree,omitempty"`
Split SplitConfig `yaml:"split,omitempty"`
Hooks HooksConfig `yaml:"hooks,omitempty"`
MaxConcurrency *int `yaml:"maxConcurrency,omitempty"` // Pointer to distinguish unset from 0
}
ProjectConfig represents the project-level configuration stored in .stackit.yaml This file is committed to the repository and shared across the team. Team settings can be overridden by personal git config (git config > project config > defaults).
func LoadProjectConfig ¶
func LoadProjectConfig(repoRoot string) (*ProjectConfig, error)
LoadProjectConfig reads the project configuration from .stackit.yaml in the repo root. Returns an empty config (not an error) if the file doesn't exist.
func (*ProjectConfig) GetMaxConcurrency ¶
func (c *ProjectConfig) GetMaxConcurrency() int
GetMaxConcurrency returns the max concurrency value (caller should check HasMaxConcurrency first)
func (*ProjectConfig) GetNavigationShowMerged ¶
func (c *ProjectConfig) GetNavigationShowMerged() bool
GetNavigationShowMerged returns the navigation.showMerged value (caller should check HasNavigationShowMerged first)
func (*ProjectConfig) GetSubmitDraft ¶
func (c *ProjectConfig) GetSubmitDraft() bool
GetSubmitDraft returns the submit draft value (caller should check HasSubmitDraft first)
func (*ProjectConfig) GetSubmitFooter ¶
func (c *ProjectConfig) GetSubmitFooter() bool
GetSubmitFooter returns the submit footer value (caller should check HasSubmitFooter first)
func (*ProjectConfig) GetWorktreeAutoClean ¶
func (c *ProjectConfig) GetWorktreeAutoClean() bool
GetWorktreeAutoClean returns the worktree auto clean value (caller should check HasWorktreeAutoClean first)
func (*ProjectConfig) HasBranchPattern ¶
func (c *ProjectConfig) HasBranchPattern() bool
HasBranchPattern returns true if a branch naming pattern is configured
func (*ProjectConfig) HasCICommand ¶
func (c *ProjectConfig) HasCICommand() bool
HasCICommand returns true if a CI command is configured
func (*ProjectConfig) HasCITimeout ¶
func (c *ProjectConfig) HasCITimeout() bool
HasCITimeout returns true if a CI timeout is configured
func (*ProjectConfig) HasMaxConcurrency ¶
func (c *ProjectConfig) HasMaxConcurrency() bool
HasMaxConcurrency returns true if max concurrency is configured
func (*ProjectConfig) HasMergeMethod ¶
func (c *ProjectConfig) HasMergeMethod() bool
HasMergeMethod returns true if a merge method is configured
func (*ProjectConfig) HasNavigationLocation ¶
func (c *ProjectConfig) HasNavigationLocation() bool
HasNavigationLocation returns true if navigation.location is configured
func (*ProjectConfig) HasNavigationMarker ¶
func (c *ProjectConfig) HasNavigationMarker() bool
HasNavigationMarker returns true if navigation.marker is configured
func (*ProjectConfig) HasNavigationShowMerged ¶
func (c *ProjectConfig) HasNavigationShowMerged() bool
HasNavigationShowMerged returns true if navigation.showMerged is configured
func (*ProjectConfig) HasNavigationWhen ¶
func (c *ProjectConfig) HasNavigationWhen() bool
HasNavigationWhen returns true if navigation.when is configured
func (*ProjectConfig) HasPostWorktreeCreateHooks ¶
func (c *ProjectConfig) HasPostWorktreeCreateHooks() bool
HasPostWorktreeCreateHooks returns true if there are any post-worktree-create hooks configured
func (*ProjectConfig) HasSplitHunkSelector ¶
func (c *ProjectConfig) HasSplitHunkSelector() bool
HasSplitHunkSelector returns true if split hunk selector is configured
func (*ProjectConfig) HasSubmitAssignees ¶
func (c *ProjectConfig) HasSubmitAssignees() bool
HasSubmitAssignees returns true if default assignees are configured
func (*ProjectConfig) HasSubmitDraft ¶
func (c *ProjectConfig) HasSubmitDraft() bool
HasSubmitDraft returns true if the submit draft setting is configured
func (*ProjectConfig) HasSubmitFooter ¶
func (c *ProjectConfig) HasSubmitFooter() bool
HasSubmitFooter returns true if the submit footer setting is configured
func (*ProjectConfig) HasSubmitLabels ¶
func (c *ProjectConfig) HasSubmitLabels() bool
HasSubmitLabels returns true if default labels are configured
func (*ProjectConfig) HasSubmitReviewers ¶
func (c *ProjectConfig) HasSubmitReviewers() bool
HasSubmitReviewers returns true if default reviewers are configured
func (*ProjectConfig) HasSubmitWeb ¶
func (c *ProjectConfig) HasSubmitWeb() bool
HasSubmitWeb returns true if the submit web setting is configured
func (*ProjectConfig) HasTrunk ¶
func (c *ProjectConfig) HasTrunk() bool
HasTrunk returns true if a trunk branch is configured
func (*ProjectConfig) HasTrunks ¶
func (c *ProjectConfig) HasTrunks() bool
HasTrunks returns true if additional trunk branches are configured
func (*ProjectConfig) HasUndoDepth ¶
func (c *ProjectConfig) HasUndoDepth() bool
HasUndoDepth returns true if undo depth is configured
func (*ProjectConfig) HasUndoEnabled ¶ added in v0.19.0
func (c *ProjectConfig) HasUndoEnabled() bool
HasUndoEnabled returns true if undo enabled is configured
func (*ProjectConfig) HasWorktreeAutoClean ¶
func (c *ProjectConfig) HasWorktreeAutoClean() bool
HasWorktreeAutoClean returns true if worktree auto clean is configured
func (*ProjectConfig) HasWorktreeBasePath ¶
func (c *ProjectConfig) HasWorktreeBasePath() bool
HasWorktreeBasePath returns true if worktree base path is configured
func (*ProjectConfig) Validate ¶
func (c *ProjectConfig) Validate() error
Validate checks the configuration for invalid values
type RepoConfig ¶
type RepoConfig struct {
Trunk *string `json:"trunk,omitempty"`
Trunks []string `json:"trunks,omitempty"`
IsGithubIntegrationEnabled *bool `json:"isGithubIntegrationEnabled,omitempty"`
BranchNamePattern *string `json:"branchNamePattern,omitempty"`
UndoStackDepth *int `json:"undo.stackDepth,omitempty"`
MaxConcurrency *int `json:"maxConcurrency,omitempty"` // Maximum concurrent validation operations
WorktreeBasePath *string `json:"worktree.basePath,omitempty"`
WorktreeAutoClean *bool `json:"worktree.autoClean,omitempty"`
MergeMethod *string `json:"merge.method,omitempty"`
CombineCICommand *string `json:"combine.ciCommand,omitempty"` // Deprecated: use CICommand
CombineCITimeout *int `json:"combine.ciTimeout,omitempty"` // Deprecated: use CITimeout
CICommand *string `json:"ci.command,omitempty"` // Unified CI command for all validation
CITimeout *int `json:"ci.timeout,omitempty"` // Unified CI timeout in seconds
SplitHunkSelector *string `json:"split.hunkSelector,omitempty"`
ApprovedPostWorktreeCreateHooks []string `json:"hooks.approvedPostWorktreeCreate,omitempty"`
}
RepoConfig represents the legacy JSON-based repository configuration. This struct is used only for migration from the old .stackit_config JSON format.
func (*RepoConfig) GetBranchPattern ¶
func (c *RepoConfig) GetBranchPattern() BranchPattern
GetBranchPattern returns the branch name pattern as a BranchPattern type. Always returns a valid pattern (default if not set or invalid).
type Section ¶
type Section struct {
// Name is the internal identifier (matches Option.Section)
Name string
// Title is the display title for templates (empty = no header comment)
Title string
// DocsTitle is the display title for documentation (empty = skip in docs)
DocsTitle string
}
Section defines a group of related options for documentation and templates.
func GetSectionByName ¶
GetSectionByName returns the Section with the given name, or nil if not found.
type SplitConfig ¶
type SplitConfig struct {
HunkSelector string `yaml:"hunkSelector,omitempty"`
}
SplitConfig contains split settings
type SubmitConfig ¶
type SubmitConfig struct {
Draft *bool `yaml:"draft,omitempty"` // Pointer to distinguish unset from false
Web string `yaml:"web,omitempty"` // "always", "created", "never"
Labels []string `yaml:"labels,omitempty"` // Default labels for PRs
Reviewers []string `yaml:"reviewers,omitempty"` // Default reviewers for PRs
Assignees []string `yaml:"assignees,omitempty"` // Default assignees for PRs
}
SubmitConfig contains PR submission configuration
type UndoConfig ¶
type UndoConfig struct {
Depth int `yaml:"depth,omitempty"`
Enabled *bool `yaml:"enabled,omitempty"`
}
UndoConfig contains undo settings
type WorktreeConfig ¶
type WorktreeConfig struct {
BasePath string `yaml:"basePath,omitempty"`
AutoClean *bool `yaml:"autoClean,omitempty"` // Pointer to distinguish unset from false
}
WorktreeConfig contains worktree settings