Function Signature
func Expand(path string) (string, error)
Description
The Expand() function expands the path to include the home directory if the path is prefixed with ~. If the path doesn’t start with ~, it returns the path as-is.
Parameters
The file path to expand. If it starts with ~, it will be expanded to the full home directory path.
Return Values
The expanded path with ~ replaced by the home directory, or the original path if no expansion was needed
An error if:
- The path attempts to expand a user-specific home directory (e.g.,
~user/path)
- The home directory cannot be detected (from
Dir())
Returns nil on success. Behavior
Expansion Rules
- Empty path: Returns the path as-is (empty string)
- No tilde prefix: Returns the path unchanged
- Tilde only (
~): Returns the home directory
- Tilde with separator (
~/ or ~\): Replaces ~ with the home directory and joins the remaining path
- User-specific (
~user/): Returns an error (not supported)
Limitations
Expand() cannot expand user-specific home directories. Paths like ~otheruser/documents will return an error: "cannot expand user-specific home dir".
Usage Examples
Basic Path Expansion
import "github.com/mitchellh/go-homedir"
func main() {
path := "~/documents/file.txt"
expanded, err := homedir.Expand(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(expanded)
// Output (example): /home/username/documents/file.txt
}
Paths Without Tilde
path := "/absolute/path/to/file"
expanded, err := homedir.Expand(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(expanded)
// Output: /absolute/path/to/file (unchanged)
Just the Tilde
path := "~"
expanded, err := homedir.Expand(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(expanded)
// Output (example): /home/username
Windows Paths
// Works on Windows too
path := "~\\Documents\\file.txt"
expanded, err := homedir.Expand(path)
if err != nil {
log.Fatal(err)
}
fmt.Println(expanded)
// Output (example): C:\Users\username\Documents\file.txt
Error Handling
User-Specific Home Directory Error
path := "~otheruser/documents"
expanded, err := homedir.Expand(path)
if err != nil {
// Error: "cannot expand user-specific home dir"
fmt.Println("Cannot expand:", err)
return
}
Home Directory Detection Error
path := "~/config"
expanded, err := homedir.Expand(path)
if err != nil {
// Error from Dir() if home directory cannot be detected
log.Fatalf("Failed to expand path: %v", err)
}
fmt.Println(expanded)
Implementation Details
Internally, Expand() uses:
Dir() to get the home directoryfilepath.Join() to properly combine the home directory with the remaining path segments
This ensures cross-platform compatibility with proper path separators.
- Dir() - Used internally to get the home directory
- Reset() - Clear the home directory cache if needed
