Documentation
¶
Overview ¶
Package paths provides centralized path handling for dodot.
This package implements the XDG Base Directory specification and provides a consistent API for all path operations throughout the dodot codebase. It handles:
- Dotfiles root directory discovery and configuration
- XDG directory structure (data, config, cache)
- Path normalization and expansion
- Pack-specific path generation
- State and backup file locations
Environment Variables ¶
The package respects the following environment variables:
- DOTFILES_ROOT: Primary location for dotfiles (default: ~/dotfiles)
- DODOT_DATA_DIR: Override XDG data directory (default: $XDG_DATA_HOME/dodot)
- DODOT_CONFIG_DIR: Override XDG config directory (default: $XDG_CONFIG_HOME/dodot)
- DODOT_CACHE_DIR: Override XDG cache directory (default: $XDG_CACHE_HOME/dodot)
XDG Base Directory Structure ¶
dodot follows the XDG Base Directory specification:
- Data: $XDG_DATA_HOME/dodot (persistent data, state files, backups)
- Config: $XDG_CONFIG_HOME/dodot (user configuration)
- Cache: $XDG_CACHE_HOME/dodot (temporary files, caches)
Usage ¶
import "github.com/arthur-debert/dodot/pkg/paths"
// Create a new Paths instance
p, err := paths.New("") // Auto-detect dotfiles root
if err != nil {
log.Fatal(err)
}
// Get various paths
root := p.DotfilesRoot() // /home/user/dotfiles
packPath := p.PackPath("vim") // /home/user/dotfiles/vim
stateFile := p.StatePath("vim", "provision") // $XDG_DATA_HOME/dodot/state/vim/install.json
// Check if a path is within dotfiles
isInside, err := p.IsInDotfiles("/home/user/dotfiles/vim/vimrc")
// isInside == true
Package paths provides centralized path handling for dodot. It implements XDG Base Directory specification compliance and provides a consistent API for all path operations in the codebase.
Index ¶
- Constants
- func CommonPrefix(paths ...string) string
- func ContainsPath(parent, child string) bool
- func ExpandHome(path string) string
- func GetHomeDirectory() (string, error)
- func GetHomeDirectoryWithDefault(defaultDir string) string
- func GetShellScriptPath(shell string) string
- func IsAbsolutePath(path string) bool
- func IsHiddenPath(path string) bool
- func JoinPaths(elem ...string) (string, error)
- func MustValidatePath(path string)
- func PathDepth(path string) int
- func RelativePath(base, target string) (string, error)
- func ResolveShellScriptPath(scriptName string) (string, error)
- func SanitizePath(path string) string
- func SplitPath(path string) (dir, file string)
- func ValidatePackName(name string) error
- func ValidatePath(path string) error
- func ValidatePathSecurity(path string) error
- type Paths
Constants ¶
const ( // EnvDotfilesRoot is the primary environment variable for dotfiles location EnvDotfilesRoot = "DOTFILES_ROOT" // EnvDodotDataDir overrides the XDG data directory for dodot EnvDodotDataDir = "DODOT_DATA_DIR" // EnvDodotConfigDir overrides the XDG config directory for dodot EnvDodotConfigDir = "DODOT_CONFIG_DIR" // EnvDodotCacheDir overrides the XDG cache directory for dodot EnvDodotCacheDir = "DODOT_CACHE_DIR" // EnvHome is the standard home directory variable EnvHome = "HOME" )
Environment variable names
const ( // DefaultDotfilesDir is the default directory name for dotfiles DefaultDotfilesDir = "dotfiles" // DodotDirName is the directory name for dodot-specific files DodotDirName = "dodot" // PackConfigFile is the name of the pack configuration file PackConfigFile = ".dodot.toml" // StateDir is the subdirectory for state files StateDir = "state" // TemplatesDir is the subdirectory for templates TemplatesDir = "templates" // DeployedDir is the subdirectory for deployed files DeployedDir = "deployed" // ShellDir is the subdirectory for shell scripts ShellDir = "shell" // ProvisionDir is the subdirectory for provision sentinels ProvisionDir = "provision" // HomebrewDir is the subdirectory for homebrew sentinels HomebrewDir = "homebrew" // InitScriptName is the name of the init script InitScriptName = "dodot-init.sh" // LogFileName is the name of the log file LogFileName = "dodot.log" )
Default directories and files IMPORTANT: These constants define dodot's internal datastore structure and are NOT user-configurable. They must remain consistent across all dodot installations to ensure proper operation. User-configurable paths should be added to pkg/config instead.
Variables ¶
This section is empty.
Functions ¶
func CommonPrefix ¶
CommonPrefix returns the longest common prefix of the provided paths. Returns empty string if paths have no common prefix.
func ContainsPath ¶
ContainsPath checks if child is contained within parent. Both paths are normalized before comparison.
func ExpandHome ¶
ExpandHome is a utility function that expands ~ in paths This is exposed for compatibility with existing code
func GetHomeDirectory ¶
GetHomeDirectory returns the user's home directory with proper error handling This is migrated from pkg/utils/home.go
func GetHomeDirectoryWithDefault ¶
GetHomeDirectoryWithDefault returns the home directory or a default value This is migrated from pkg/utils/home.go
func GetShellScriptPath ¶ added in v0.1.1
GetShellScriptPath returns the path to the shell integration script It uses the resolved path if found, otherwise returns the expected installation path
func IsAbsolutePath ¶
IsAbsolutePath returns true if the path is absolute. This is a cross-platform wrapper around filepath.IsAbs.
func IsHiddenPath ¶
IsHiddenPath returns true if the path represents a hidden file or directory. On Unix-like systems, this means the basename starts with a dot. On Windows, this would check file attributes (not implemented here).
func JoinPaths ¶
JoinPaths safely joins path elements, ensuring proper separators. This is a wrapper around filepath.Join that also validates the result.
func MustValidatePath ¶
func MustValidatePath(path string)
MustValidatePath panics if the path is invalid. This should only be used with hardcoded paths that must be valid.
func PathDepth ¶
PathDepth returns the depth of a path (number of directories). For example: "/" = 0, "/a" = 1, "/a/b" = 2
func RelativePath ¶
RelativePath returns the relative path from base to target. Returns an error if the paths cannot be made relative.
func ResolveShellScriptPath ¶ added in v0.1.1
ResolveShellScriptPath finds the shell integration script with fallback logic It first tries the installed location, then falls back to development location
func SanitizePath ¶
SanitizePath attempts to clean and make a path safe for use. It: - Normalizes path separators - Removes redundant separators - Resolves . and .. elements - Removes trailing separators (except for root)
func SplitPath ¶
SplitPath splits a path into its directory and file components. This is a wrapper around filepath.Split that also handles edge cases.
func ValidatePackName ¶
ValidatePackName ensures a pack name is valid for use in paths. Pack names must: - Not be empty - Not contain path separators - Not contain special characters that could cause issues - Not be reserved names (. or ..)
func ValidatePath ¶
ValidatePath performs comprehensive validation on a path. It checks for: - Empty paths - Invalid characters (on Windows) - Path traversal attempts - Excessive path length
func ValidatePathSecurity ¶
ValidatePathSecurity performs security-focused validation on a path. It checks for common path traversal attacks and suspicious patterns.
Types ¶
type Paths ¶
type Paths interface {
DotfilesRoot() string
UsedFallback() bool
PackPath(packName string) string
PackConfigPath(packName string) string
DataDir() string
ConfigDir() string
CacheDir() string
StateDir() string
TemplatesDir() string
StatePath(packName, handlerName string) string
NormalizePath(path string) (string, error)
IsInDotfiles(path string) (bool, error)
DeployedDir() string
ShellProfileDir() string
PathDir() string
ShellSourceDir() string
SymlinkDir() string
ShellDir() string
InitScriptPath() string
ProvisionDir() string
HomebrewDir() string
SentinelPath(handlerType, packName string) string
LogFilePath() string
MapPackFileToSystem(pack *types.Pack, relPath string) string
MapSystemFileToPack(pack *types.Pack, systemPath string) string
PackHandlerDir(packName, handlerName string) string
}
Paths provides centralized path management for dodot
Source Files