feat!: Load ruler file dynamically

CHANGELOG.md

@@ -14,6 +14,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 
 - The `previewer` script no longer skips non-regular files (#2327).
 - Line numbers now take up less space when both `number` and `relativenumber` are enabled (#2331).
+- Changes have been made to ruler configuration (#2338):
+  - The ruler file is no longer experimental.
+  - The ruler file will be used by default unless `rulerfmt` (now a blank string by default) is specified.
+  - The ruler file is no longer read from fixed locations like `~/.config/lf/ruler`, and instead the `rulerfile` option has been repurposed to specify the path of the ruler file.
 
 ### Added
 

complete.go

@@ -422,7 +422,7 @@ func completeCmd(acc []rune) (matches []compMatch, result string) {
 			break
 		}
 		switch f[1] {
-		case "cleaner", "previewer":
+		case "cleaner", "previewer", "rulerfile":
 			matches, result = matchCmdFile(f[2], false)
 		case "filtermethod", "searchmethod":
 			matches, result = matchWord(f[2], []string{"glob", "regex", "text"})

doc.md

@@ -301,8 +301,8 @@ The following options can be used to customize the behavior of lf:
 	relativenumber    bool      (default false)
 	reverse           bool      (default false)
 	roundbox          bool      (default false)
-	rulerfile         bool      (default false)
-	rulerfmt          string    (default "  %a|  %p|  \033[7;31m %m \033[0m|  \033[7;33m %c \033[0m|  \033[7;35m %s \033[0m|  \033[7;36m %v \033[0m|  \033[7;34m %f \033[0m|  %i/%t")
+	rulerfile         string    (default "")
+	rulerfmt          string    (default "")
 	scrolloff         int       (default 0)
 	searchmethod      string    (default 'text')
 	selectfmt         string    (default "\033[7;35m")
@@ -450,12 +450,6 @@ The icons file should be located at:
 	Unix     /etc/lf/icons             ~/.config/lf/icons
 	Windows  C:\ProgramData\lf\icons   C:\Users\<user>\AppData\Roaming\lf\icons
 
-The ruler file should be located at:
-
-	OS       system-wide               user-specific
-	Unix     /etc/lf/ruler             ~/.config/lf/ruler
-	Windows  C:\ProgramData\lf\ruler   C:\Users\<user>\AppData\Roaming\lf\ruler
-
 The selection file should be located at:
 
 	Unix     ~/.local/share/lf/files
@@ -1109,14 +1103,17 @@ Reverse the direction of sort.
 
 Draw rounded outer corners when the `drawbox` option is enabled.
 
-## rulerfile (bool) (default false)
+## rulerfile (string) (default ``)
 
-Use the ruler file instead of the `rulerfmt` and `statfmt` options when drawing the ruler at the bottom.
+Set the path of the ruler file.
+If not set, then a default template will be used for the ruler.
 Refer to the [RULER section](https://github.com/gokcehan/lf/blob/master/doc.md#ruler) for more information about how the ruler file works.
 
-## rulerfmt (string) (default `  %a|  %p|  \033[7;31m %m \033[0m|  \033[7;33m %c \033[0m|  \033[7;35m %s \033[0m|  \033[7;36m %v \033[0m|  \033[7;34m %f \033[0m|  %i/%t`)
+## rulerfmt (string) (default ``)
 
 Format string of the ruler shown in the bottom right corner.
+When set, it will be used along with `statfmt` to draw the ruler, and `rulerfile` will be ignored.
+However, using `rulerfile` is preferred and this option is provided for backwards compatibility.
 
 The following special expansions are supported:
 
@@ -1209,6 +1206,8 @@ The following sort types are supported:
 ## statfmt (string) (default `\033[36m%p\033[0m| %c| %u| %g| %S| %t| -> %l`)
 
 Format string of the file info shown in the bottom left corner.
+This option has no effect unless `rulerfmt` is also set.
+Using `rulerfile` is preferred and this option is provided for backwards compatibility.
 
 The following special expansions are supported:
 
@@ -2214,9 +2213,8 @@ https://github.com/gokcehan/lf/blob/master/etc/icons_colored.example
 
 # RULER
 
-The ruler can be configured using a ruler file (refer to the [CONFIGURATION section](https://github.com/gokcehan/lf/blob/master/doc.md#configuration)).
+The ruler can be configured using the `rulerfile` option (refer to the [CONFIGURATION section](https://github.com/gokcehan/lf/blob/master/doc.md#configuration)).
 The contents of the ruler file should be a Go template which is then rendered to create the actual output (refer to https://pkg.go.dev/text/template for more details on the syntax).
-This feature is currently experimental and must be enabled via the `rulerfile` option.
 
 The following data fields are exported:
 

doc.txt

@@ -313,8 +313,8 @@ The following options can be used to customize the behavior of lf:
     relativenumber    bool      (default false)
     reverse           bool      (default false)
     roundbox          bool      (default false)
-    rulerfile         bool      (default false)
-    rulerfmt          string    (default "  %a|  %p|  \033[7;31m %m \033[0m|  \033[7;33m %c \033[0m|  \033[7;35m %s \033[0m|  \033[7;36m %v \033[0m|  \033[7;34m %f \033[0m|  %i/%t")
+    rulerfile         string    (default "")
+    rulerfmt          string    (default "")
     scrolloff         int       (default 0)
     searchmethod      string    (default 'text')
     selectfmt         string    (default "\033[7;35m")
@@ -464,12 +464,6 @@ The icons file should be located at:
     Unix     /etc/lf/icons             ~/.config/lf/icons
     Windows  C:\ProgramData\lf\icons   C:\Users\<user>\AppData\Roaming\lf\icons
 
-The ruler file should be located at:
-
-    OS       system-wide               user-specific
-    Unix     /etc/lf/ruler             ~/.config/lf/ruler
-    Windows  C:\ProgramData\lf\ruler   C:\Users\<user>\AppData\Roaming\lf\ruler
-
 The selection file should be located at:
 
     Unix     ~/.local/share/lf/files
@@ -1206,15 +1200,18 @@ roundbox (bool) (default false)
 
 Draw rounded outer corners when the drawbox option is enabled.
 
-rulerfile (bool) (default false)
+rulerfile (string) (default ``)
 
-Use the ruler file instead of the rulerfmt and statfmt options when
-drawing the ruler at the bottom. Refer to the RULER section for more
-information about how the ruler file works.
+Set the path of the ruler file. If not set, then a default template will
+be used for the ruler. Refer to the RULER section for more information
+about how the ruler file works.
 
-rulerfmt (string) (default   %a|  %p|  \033[7;31m %m \033[0m|  \033[7;33m %c \033[0m|  \033[7;35m %s \033[0m|  \033[7;36m %v \033[0m|  \033[7;34m %f \033[0m|  %i/%t)
+rulerfmt (string) (default ``)
 
-Format string of the ruler shown in the bottom right corner.
+Format string of the ruler shown in the bottom right corner. When set,
+it will be used along with statfmt to draw the ruler, and rulerfile will
+be ignored. However, using rulerfile is preferred and this option is
+provided for backwards compatibility.
 
 The following special expansions are supported:
 
@@ -1314,7 +1311,9 @@ The following sort types are supported:
 
 statfmt (string) (default \033[36m%p\033[0m| %c| %u| %g| %S| %t| -> %l)
 
-Format string of the file info shown in the bottom left corner.
+Format string of the file info shown in the bottom left corner. This
+option has no effect unless rulerfmt is also set. Using rulerfile is
+preferred and this option is provided for backwards compatibility.
 
 The following special expansions are supported:
 
@@ -2486,12 +2485,10 @@ https://github.com/gokcehan/lf/blob/master/etc/icons_colored.example
 
 RULER
 
-The ruler can be configured using a ruler file (refer to the
+The ruler can be configured using the rulerfile option (refer to the
 CONFIGURATION section). The contents of the ruler file should be a Go
 template which is then rendered to create the actual output (refer to
-https://pkg.go.dev/text/template for more details on the syntax). This
-feature is currently experimental and must be enabled via the rulerfile
-option.
+https://pkg.go.dev/text/template for more details on the syntax).
 
 The following data fields are exported:
 

eval.go

@@ -155,8 +155,6 @@ func (e *setExpr) eval(app *app, _ []string) {
 		}
 	case "roundbox", "noroundbox", "roundbox!":
 		err = applyBoolOpt(&gOpts.roundbox, e)
-	case "rulerfile", "norulerfile", "rulerfile!":
-		err = applyBoolOpt(&gOpts.rulerfile, e)
 	case "showbinds", "noshowbinds", "showbinds!":
 		err = applyBoolOpt(&gOpts.showbinds, e)
 	case "smartcase", "nosmartcase", "smartcase!":
@@ -336,6 +334,9 @@ func (e *setExpr) eval(app *app, _ []string) {
 		app.ui.wins = getWins(app.ui.screen)
 		app.nav.resize(app.ui)
 		app.ui.loadFile(app, true)
+	case "rulerfile", "norulerfile", "rulerfile!":
+		gOpts.rulerfile = replaceTilde(e.val)
+		app.ui.ruler, app.ui.rulerErr = parseRuler(gOpts.rulerfile)
 	case "rulerfmt":
 		gOpts.rulerfmt = e.val
 	case "scrolloff":

lf.1

@@ -1,6 +1,6 @@
 .\" Automatically generated by Pandoc 3.7.0.2
 .\"
-.TH "LF" "1" "2026\-01\-11" "r41" "DOCUMENTATION"
+.TH "LF" "1" "2026\-01\-12" "r41" "DOCUMENTATION"
 .SH NAME
 lf \- terminal file manager
 .SH SYNOPSIS
@@ -325,8 +325,8 @@ ratios            []int     (default \(aq1:2:3\(aq)
 relativenumber    bool      (default false)
 reverse           bool      (default false)
 roundbox          bool      (default false)
-rulerfile         bool      (default false)
-rulerfmt          string    (default \(dq  %a|  %p|  \(rs033[7;31m %m \(rs033[0m|  \(rs033[7;33m %c \(rs033[0m|  \(rs033[7;35m %s \(rs033[0m|  \(rs033[7;36m %v \(rs033[0m|  \(rs033[7;34m %f \(rs033[0m|  %i/%t\(dq)
+rulerfile         string    (default \(dq\(dq)
+rulerfmt          string    (default \(dq\(dq)
 scrolloff         int       (default 0)
 searchmethod      string    (default \(aqtext\(aq)
 selectfmt         string    (default \(dq\(rs033[7;35m\(dq)
@@ -492,14 +492,6 @@ Unix     /etc/lf/icons             \(ti/.config/lf/icons
 Windows  C:\(rsProgramData\(rslf\(rsicons   C:\(rsUsers\(rs<user>\(rsAppData\(rsRoaming\(rslf\(rsicons
 .EE
 .PP
-The ruler file should be located at:
-.IP
-.EX
-OS       system\-wide               user\-specific
-Unix     /etc/lf/ruler             \(ti/.config/lf/ruler
-Windows  C:\(rsProgramData\(rslf\(rsruler   C:\(rsUsers\(rs<user>\(rsAppData\(rsRoaming\(rslf\(rsruler
-.EE
-.PP
 The selection file should be located at:
 .IP
 .EX
@@ -1068,16 +1060,20 @@ Reverse the direction of sort.
 .SS roundbox (bool) (default false)
 Draw rounded outer corners when the \f[CR]drawbox\f[R] option is
 enabled.
-.SS rulerfile (bool) (default false)
-Use the ruler file instead of the \f[CR]rulerfmt\f[R] and
-\f[CR]statfmt\f[R] options when drawing the ruler at the bottom.
+.SS rulerfile (string) (default \(ga\(ga)
+Set the path of the ruler file.
+If not set, then a default template will be used for the ruler.
 Refer to the \c
 .UR https://github.com/gokcehan/lf/blob/master/doc.md#ruler
 RULER section
 .UE \c
 \ for more information about how the ruler file works.
-.SS rulerfmt (string) (default \f[CR]  %a|  %p|  \(rs033[7;31m %m \(rs033[0m|  \(rs033[7;33m %c \(rs033[0m|  \(rs033[7;35m %s \(rs033[0m|  \(rs033[7;36m %v \(rs033[0m|  \(rs033[7;34m %f \(rs033[0m|  %i/%t\f[R])
+.SS rulerfmt (string) (default \(ga\(ga)
 Format string of the ruler shown in the bottom right corner.
+When set, it will be used along with \f[CR]statfmt\f[R] to draw the
+ruler, and \f[CR]rulerfile\f[R] will be ignored.
+However, using \f[CR]rulerfile\f[R] is preferred and this option is
+provided for backwards compatibility.
 .PP
 The following special expansions are supported:
 .IP
@@ -1168,6 +1164,9 @@ custom    property defined via \(gaaddcustominfo\(ga (empty by default)
 .EE
 .SS statfmt (string) (default \f[CR]\(rs033[36m%p\(rs033[0m| %c| %u| %g| %S| %t| \-> %l\f[R])
 Format string of the file info shown in the bottom left corner.
+This option has no effect unless \f[CR]rulerfmt\f[R] is also set.
+Using \f[CR]rulerfile\f[R] is preferred and this option is provided for
+backwards compatibility.
 .PP
 The following special expansions are supported:
 .IP
@@ -2514,7 +2513,8 @@ A sample colored icons file can be found at \c
 .UR https://github.com/gokcehan/lf/blob/master/etc/icons_colored.example
 .UE \c
 .SH RULER
-The ruler can be configured using a ruler file (refer to the \c
+The ruler can be configured using the \f[CR]rulerfile\f[R] option (refer
+to the \c
 .UR https://github.com/gokcehan/lf/blob/master/doc.md#configuration
 CONFIGURATION section
 .UE \c
@@ -2524,8 +2524,6 @@ rendered to create the actual output (refer to \c
 .UR https://pkg.go.dev/text/template
 .UE \c
 \ for more details on the syntax).
-This feature is currently experimental and must be enabled via the
-\f[CR]rulerfile\f[R] option.
 .PP
 The following data fields are exported:
 .IP

opts.go

@@ -92,7 +92,7 @@ var gOpts struct {
 	relativenumber   bool
 	reverse          bool
 	roundbox         bool
-	rulerfile        bool
+	rulerfile        string
 	rulerfmt         string
 	scrolloff        int
 	searchmethod     searchMethod
@@ -255,8 +255,8 @@ func init() {
 	gOpts.relativenumber = false
 	gOpts.reverse = false
 	gOpts.roundbox = false
-	gOpts.rulerfile = false
-	gOpts.rulerfmt = "  %a|  %p|  \033[7;31m %m \033[0m|  \033[7;33m %c \033[0m|  \033[7;35m %s \033[0m|  \033[7;36m %v \033[0m|  \033[7;34m %f \033[0m|  %i/%t"
+	gOpts.rulerfile = ""
+	gOpts.rulerfmt = ""
 	gOpts.scrolloff = 0
 	gOpts.searchmethod = textSearch
 	gOpts.selectfmt = "\033[7;35m"

os.go

@@ -38,7 +38,6 @@ var (
 	gConfigPaths []string
 	gColorsPaths []string
 	gIconsPaths  []string
-	gRulerPaths  []string
 	gFilesPath   string
 	gMarksPath   string
 	gTagsPath    string
@@ -106,11 +105,6 @@ func init() {
 		filepath.Join(config, "lf", "icons"),
 	}
 
-	gRulerPaths = []string{
-		filepath.Join("/etc", "lf", "ruler"),
-		filepath.Join(config, "lf", "ruler"),
-	}
-
 	data := cmp.Or(
 		os.Getenv("LF_DATA_HOME"),
 		os.Getenv("XDG_DATA_HOME"),

os_windows.go

@@ -36,7 +36,6 @@ var (
 	gConfigPaths []string
 	gColorsPaths []string
 	gIconsPaths  []string
-	gRulerPaths  []string
 	gFilesPath   string
 	gTagsPath    string
 	gMarksPath   string
@@ -96,11 +95,6 @@ func init() {
 		filepath.Join(config, "lf", "icons"),
 	}
 
-	gRulerPaths = []string{
-		filepath.Join(os.Getenv("ProgramData"), "lf", "ruler"),
-		filepath.Join(config, "lf", "ruler"),
-	}
-
 	data := cmp.Or(
 		os.Getenv("LF_DATA_HOME"),
 		os.Getenv("XDG_DATA_HOME"),

ruler.go

@@ -2,8 +2,8 @@ package main
 
 import (
 	"fmt"
-	"log"
 	"os"
+	"path/filepath"
 	"strings"
 	"text/template"
 
@@ -51,7 +51,7 @@ type rulerData struct {
 	Stat             *statData
 }
 
-func parseRuler() (*template.Template, error) {
+func parseRuler(path string) (*template.Template, error) {
 	funcs := template.FuncMap{
 		"df":       func() string { return diskFree(".") },
 		"env":      os.Getenv,
@@ -62,17 +62,11 @@ func parseRuler() (*template.Template, error) {
 		"upper":    strings.ToUpper,
 	}
 
-	for i := len(gRulerPaths) - 1; i >= 0; i-- {
-		path := gRulerPaths[i]
-		if _, err := os.Stat(path); os.IsNotExist(err) {
-			continue
-		}
-
-		log.Printf("reading file: %s", path)
-		return template.New("ruler").Funcs(funcs).ParseFiles(path)
+	if path == "" {
+		return template.New("ruler").Funcs(funcs).Parse(gDefaultRuler)
 	}
 
-	return template.New("ruler").Funcs(funcs).Parse(gDefaultRuler)
+	return template.New(filepath.Base(path)).Funcs(funcs).ParseFiles(path)
 }
 
 func renderRuler(ruler *template.Template, data rulerData, width int) (string, string, error) {

ui.go

@@ -695,7 +695,7 @@ func newUI(screen tcell.Screen) *ui {
 		currentFile: "",
 		sxScreen:    sixelScreen{},
 	}
-	ui.ruler, ui.rulerErr = parseRuler()
+	ui.ruler, ui.rulerErr = parseRuler(gOpts.rulerfile)
 
 	go ui.pollEvents()
 
@@ -1280,7 +1280,7 @@ func (ui *ui) draw(nav *nav) {
 
 	switch ui.cmdPrefix {
 	case "":
-		if gOpts.rulerfile {
+		if gOpts.rulerfmt == "" {
 			ui.drawRulerFile(nav)
 		} else {
 			ui.drawStat(nav)