jandedobbeleer Segment Documentation Reference
Go-to-Documentation Type Mapping
When reading a segment's Go source to document its options, determine the type from the
Provider method used to read the option value:
| Go method call | Documentation type |
|---|---|
options.Bool(option, default) |
boolean |
options.String(option, default) |
string |
options.StringArray(option, default) |
[]string |
options.Int(option, default) |
int |
options.Float64(option, default) |
float64 |
options.KeyValueMap(option, default) |
map[string]string |
options.Color(option, default) |
string |
options.Template(option, default, ctx) |
string |
options.Any(option, default) |
any |
Extracting Options from Go Source
Options are declared as options.Option string constants in the segment's const block:
const (
BranchIcon options.Option = "branch_icon" // option name used in config
NativeStatus options.Option = "native_status"
)
The option name is the string literal value (e.g., "branch_icon").
The type and default value come from the getter call in Enabled() or init-like methods:
s.icon = s.options.String(BranchIcon, "\uE0A0")
// ^^^^^^ → string type, "\uE0A0" → default
Shared options
The following options are defined in src/segments/options/map.go and available to all
segments without appearing in a segment-specific const block:
| Option name | Type | Default |
|---|---|---|
always_enabled |
boolean |
false |
display_default |
boolean |
true |
display_error |
boolean |
true |
http_timeout |
int |
20 |
cache_duration |
int |
varies |
access_token |
string |
"" |
refresh_token |
string |
"" |
version_url_template |
string |
"" |
files |
[]string |
varies |
Extracting Template Properties from Go Source
Template properties are values available inside the segment's template string.
Rules for what becomes a template property:
- Exported struct fields (capitalized) on the segment struct →
.FieldName - Unexported fields are not accessible in templates
- Nested struct fields use dot notation: a field
Working ScmStatusexposes.Working.Modified,.Working.Added, etc. - Zero-argument methods with a single return value →
.MethodName - Document fields that are assigned in
Enabled()or its callees, not every inherited field from embedded structs is populated by every segment
The default template comes from the Template() method:
func (s *MySegment) Template() string {
return " {{ .FieldName }} "
}
Nested struct subsection convention
When a property's type is itself a struct, add an #### TypeName subsection within
the Properties table section listing its exported fields. Example:
#### Status
| Name | Type | Description |
| ---- | ---- | ----------- |
| `.Modified` | `int` | Number of modified files |
| `.Added` | `int` | Number of added files |
| `.Deleted` | `int` | Number of deleted files |
| `.Untracked` | `int` | Number of untracked files |
| `.Changed` | `boolean` | Whether any changes exist |
Key Source Files for Inherited Fields
When a segment embeds a base struct, its inherited fields may also be template properties. Check these files to discover what fields are available:
| File | What it defines |
|---|---|
src/segments/options/map.go |
Provider interface method signatures; shared Option constants |
src/segments/base.go |
Base struct embedded by all segments; provides options, env |
src/segments/scm.go |
ScmStatus type with working/staging status fields (git, mercurial, etc.) |
src/segments/language.go |
Version type and language base fields (Python, Node, Go, etc.) |