go-homedir

go-homedir is a Go library for detecting the user's home directory without the use of cgo, enabling cross-compilation. It provides functions to get the home directory and expand tilde paths, with built-in caching for performance.

Package Information

• Package Name: github.com/mitchellh/go-homedir
• Package Type: golang
• Language: Go
• Installation: go get github.com/mitchellh/go-homedir

Core Imports

import "github.com/mitchellh/go-homedir"

Or with an alias:

import hd "github.com/mitchellh/go-homedir"

Basic Usage

package main

import (
	"fmt"
	"log"

	"github.com/mitchellh/go-homedir"
)

func main() {
	// Get the home directory
	dir, err := homedir.Dir()
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Home directory:", dir)

	// Expand a path with tilde
	expanded, err := homedir.Expand("~/.config/myapp")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Expanded path:", expanded)
}

Capabilities

Home Directory Detection

Detects the user's home directory using OS-specific methods without requiring cgo. This enables cross-compilation while maintaining functionality across Windows, macOS, and Unix-like systems.

func Dir() (string, error)

Returns the home directory for the executing user. Uses an OS-specific method for discovering the home directory. An error is returned if a home directory cannot be detected.

Detection Strategy:

• Windows: Checks HOME, USERPROFILE, or HOMEDRIVE+HOMEPATH environment variables
• macOS: Checks HOME environment variable, falls back to dscl command
• Linux/Unix: Checks HOME environment variable, falls back to getent passwd, then sh -c "cd && pwd"
• Plan 9: Checks home environment variable (lowercase)

Caching: Results are cached by default for performance. Use DisableCache variable or Reset() function to control caching behavior.

Thread Safety: This function is thread-safe and uses mutex locks for cache access.

Example:

dir, err := homedir.Dir()
if err != nil {
	log.Fatal("Could not get home directory:", err)
}
fmt.Printf("Home directory: %s\n", dir)

Path Expansion

Expands paths that are prefixed with ~ to include the home directory. Paths without the tilde prefix are returned unchanged.

func Expand(path string) (string, error)

Expands the path to include the home directory if the path is prefixed with ~. If it isn't prefixed with ~, the path is returned as-is.

Parameters:

• path string: The path to expand, which may or may not start with ~

Returns:

• string: The expanded path with the home directory, or the original path if not prefixed with ~
• error: An error if the home directory cannot be determined, or if user-specific syntax is used

Behavior:

• Returns the path unchanged if it doesn't start with ~
• Expands ~/path to {home-dir}/path
• Returns an error if attempting to expand user-specific paths like ~username/path
• Empty paths are returned as-is

Example:

// Expand a config path
configPath, err := homedir.Expand("~/.config/myapp/settings.json")
if err != nil {
	log.Fatal(err)
}
fmt.Println(configPath) // Output: /home/username/.config/myapp/settings.json

// Non-tilde paths are returned unchanged
absolutePath, _ := homedir.Expand("/etc/config")
fmt.Println(absolutePath) // Output: /etc/config

Cache Management

Clears the cached home directory value, forcing the next call to Dir() to re-detect the home directory. This is primarily useful in testing scenarios.

func Reset()

Clears the cache, forcing the next call to Dir() to re-detect the home directory. This generally never has to be called, but can be useful in tests if you're modifying the home directory via the HOME environment variable or other methods.

Thread Safety: This function is thread-safe and uses mutex locks for cache manipulation.

Example:

// Initial call - detects and caches home directory
dir1, _ := homedir.Dir()

// Change HOME environment variable for testing
os.Setenv("HOME", "/tmp/test-home")

// Clear cache to force re-detection
homedir.Reset()

// Next call will use new HOME value
dir2, _ := homedir.Dir()

Cache Control

Controls whether the home directory detection result is cached for subsequent calls.

var DisableCache bool

DisableCache will disable caching of the home directory. Caching is enabled by default (DisableCache = false).

Default Value: false (caching is enabled)

Behavior:

• When false (default), the first call to Dir() caches the result for future calls
• When true, every call to Dir() re-detects the home directory
• Setting this variable affects all subsequent calls to Dir()
• This is a package-level variable and is not thread-local

Example:

// Disable caching for dynamic environments
homedir.DisableCache = true

// Each call will now re-detect the home directory
dir1, _ := homedir.Dir()
os.Setenv("HOME", "/new/home")
dir2, _ := homedir.Dir() // Will detect the new HOME value

Error Handling

The library returns errors in the following scenarios:

Dir() errors:

• Home directory cannot be detected through any available method
• On Windows: All environment variables (HOME, USERPROFILE, HOMEDRIVE, HOMEPATH) are blank or missing
• On Unix: Commands fail or return blank output

Expand() errors:

• Home directory cannot be determined (propagates errors from Dir())
• User-specific tilde syntax is used (e.g., ~username/path), which returns the error: "cannot expand user-specific home dir"

Example error handling:

dir, err := homedir.Dir()
if err != nil {
	// Handle the case where home directory cannot be determined
	log.Fatal("Failed to get home directory:", err)
}

expanded, err := homedir.Expand("~otheruser/file")
if err != nil {
	// This will error: "cannot expand user-specific home dir"
	log.Println("Expansion failed:", err)
}