
The `path/filepath` package manipulates file paths in an OS-aware way. It handles the separator difference between Unix (`/`) and Windows (`\`) so path logic is portable across platforms.

<ExamplePair>
<ExampleProse>

`filepath.Join` constructs a path from components, using the correct separator for the current OS. It also cleans redundant separators and `.` or `..` components.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "path/filepath"
)

func main() {
    p := filepath.Join("dir", "subdir", "file.txt")
    fmt.Println(p)              // dir/subdir/file.txt

    fmt.Println(filepath.Dir(p))  // dir/subdir
    fmt.Println(filepath.Base(p)) // file.txt
    fmt.Println(filepath.Ext(p))  // .txt
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`filepath.Abs` resolves a relative path to an absolute one using the current working directory. Useful when you need a canonical path to log, store in a database, or compare against other paths.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "path/filepath"
)

func main() {
    abs, err := filepath.Abs("config.yaml")
    if err != nil {
        panic(err)
    }
    fmt.Println(abs) // /home/user/project/config.yaml

    // filepath.Clean resolves . and .. without hitting the filesystem
    fmt.Println(filepath.Clean("a/b/../c")) // a/c
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`filepath.WalkDir` traverses a directory tree, calling a function for every file and directory it encounters. It is faster than the older `filepath.Walk` because it does not `stat` each entry separately.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "io/fs"
    "path/filepath"
)

func main() {
    err := filepath.WalkDir(".", func(path string, d fs.DirEntry, err error) error {
        if err != nil {
            return err
        }
        if d.IsDir() {
            fmt.Println("dir: ", path)
        } else {
            fmt.Println("file:", path)
        }
        return nil
    })
    if err != nil {
        panic(err)
    }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Always use `filepath.Join` (not `path.Join` or string concatenation) to build file paths - `filepath` handles OS-specific separators, while `path` is for URL-style slash paths only. `filepath.WalkDir` (Go 1.16+) is faster than `filepath.Walk` because it receives the `fs.DirEntry` directly from the directory read, avoiding a separate `stat` syscall per entry; prefer it for directory traversal. To skip an entire subtree in `WalkDir`, return `fs.SkipDir` when the callback is called with a directory entry. When building paths from user-supplied input, validate that the resolved absolute path starts with a known prefix before accessing the file - otherwise a `../../../etc/passwd` traversal bypasses the intended directory boundary. Use `filepath.Glob` for simple pattern matching on a single directory level; for recursive matching use `WalkDir` with an `filepath.Match` check inside the callback.
</InProduction>


filepath.Join, filepath.Dir, filepath.Base, filepath.Ext, filepath.Abs, and filepath.WalkDir for directory traversal.

File Paths


The `os` package provides functions for creating, listing, and removing directories. Most operations mirror the familiar Unix commands but are portable across operating systems.

<ExamplePair>
<ExampleProse>

`os.Mkdir` creates a single directory. It fails if the path already exists or if any intermediate directory is missing. `os.MkdirAll` creates the full path including all intermediate directories, and is idempotent - it returns `nil` if the directory already exists.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    // Create a single directory - fails if parent doesn't exist
    err := os.Mkdir("subdir", 0755)
    if err != nil {
        panic(err)
    }

    // Create a full path - idempotent, no error if already exists
    err = os.MkdirAll("a/b/c", 0755)
    if err != nil {
        panic(err)
    }

    fmt.Println("directories created")
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`os.ReadDir` lists the entries in a directory, sorted by name. Each `fs.DirEntry` provides the name, type (file or directory), and - via `Info()` - the full `fs.FileInfo`.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    entries, err := os.ReadDir(".")
    if err != nil {
        panic(err)
    }

    for _, e := range entries {
        kind := "file"
        if e.IsDir() {
            kind = "dir "
        }
        fmt.Printf("%s %s\n", kind, e.Name())
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

`os.Remove` deletes a single file or empty directory. `os.RemoveAll` deletes a path and everything under it - equivalent to `rm -rf`. `os.Getwd` returns the current working directory; `os.Chdir` changes it.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "fmt"
    "os"
)

func main() {
    os.MkdirAll("tmp/nested", 0755)

    // Remove a single empty directory
    os.Remove("tmp/nested")

    // Remove a directory tree (rm -rf equivalent)
    os.RemoveAll("tmp")

    wd, err := os.Getwd()
    if err != nil {
        panic(err)
    }
    fmt.Println("working dir:", wd)
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
`os.RemoveAll` is equivalent to `rm -rf` - no confirmation, no recycle bin, no undo. In production code, validate that the path is inside a known prefix (using `filepath.Abs` and `strings.HasPrefix`) before calling it; a bug that constructs a wrong path can delete critical data. `os.MkdirAll` is idempotent - prefer it over a stat-then-mkdir sequence, which has a TOCTOU race. `os.ReadDir` is the modern replacement for `ioutil.ReadDir` (deprecated) and is faster because it uses the `fs.DirEntry` type that avoids a `stat` call per entry when only the name and type are needed. For recursive traversal, use `filepath.WalkDir` rather than calling `os.ReadDir` recursively - it handles errors consistently and lets you skip subtrees by returning `fs.SkipDir`. Avoid `os.Chdir` in server code - it changes the working directory for the whole process, not just the current goroutine.
</InProduction>


os.Mkdir, os.MkdirAll, os.ReadDir, os.Remove, os.RemoveAll, os.Getwd, and os.Chdir for directory operations.

Directories


A line filter reads lines from standard input, transforms them, and writes results to standard output. This is the Unix filter pattern - Go binaries that follow it compose naturally with `grep`, `awk`, `sed`, and other shell tools.

<ExamplePair>
<ExampleProse>

A minimal line filter: read every line from `os.Stdin` with `bufio.Scanner` and write it to `os.Stdout` unchanged. This is the identity filter - the template you extend to add transformations.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "bufio"
    "fmt"
    "os"
)

func main() {
    scanner := bufio.NewScanner(os.Stdin)
    for scanner.Scan() {
        fmt.Println(scanner.Text())
    }
    if err := scanner.Err(); err != nil {
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Add a transformation to produce a useful filter. This example uppercases every line - a trivial but illustrative change. Replace the `strings.ToUpper` call with any line-level logic you need.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "bufio"
    "fmt"
    "os"
    "strings"
)

func main() {
    scanner := bufio.NewScanner(os.Stdin)
    for scanner.Scan() {
        fmt.Println(strings.ToUpper(scanner.Text()))
    }
    if err := scanner.Err(); err != nil {
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(1)
    }
}
```

</ExampleCode>
</ExamplePair>

<ExamplePair>
<ExampleProse>

Filters can also read from a file argument and fall back to `os.Stdin` when none is provided - the convention followed by most Unix tools. `os.Stdin` implements `io.Reader`, so `bufio.NewScanner` accepts it directly.

</ExampleProse>
<ExampleCode>

```go
package main

import (
    "bufio"
    "fmt"
    "io"
    "os"
    "strings"
)

func filter(r io.Reader) {
    scanner := bufio.NewScanner(r)
    for scanner.Scan() {
        fmt.Println(strings.ToUpper(scanner.Text()))
    }
    if err := scanner.Err(); err != nil {
        fmt.Fprintln(os.Stderr, "error:", err)
        os.Exit(1)
    }
}

func main() {
    if len(os.Args) > 1 {
        f, err := os.Open(os.Args[1])
        if err != nil {
            fmt.Fprintln(os.Stderr, err)
            os.Exit(1)
        }
        defer f.Close()
        filter(f)
    } else {
        filter(os.Stdin)
    }
}
```

</ExampleCode>
</ExamplePair>

<InProduction>
Line filters are the building blocks of shell pipelines - a Go binary that reads stdin and writes stdout composes with `grep`, `awk`, and `jq` without extra plumbing. If you wrap `os.Stdout` in a `bufio.Writer` for performance, call `w.Flush()` before `os.Exit` or returning from main - the OS flushes `os.Stdout` on normal process exit, but buffered writes in a `bufio.Writer` are not automatically flushed. Write errors to `os.Stderr`, not `os.Stdout`, so they do not corrupt the output stream in a pipeline. Exit with a non-zero code on error (`os.Exit(1)`) so downstream tools and shell scripts can detect failure. `bufio.Scanner` has a 64 KB default line limit; call `scanner.Buffer` before the first `Scan` if your input lines can exceed that.
</InProduction>


Reading from os.Stdin with bufio.Scanner, writing to os.Stdout, processing lines with strings operations, and the Unix filter pattern.