{
  "name": "ls",
  "section": 1,
  "title": "list directory contents",
  "synopsis": ["ls [-1al] [--color[=never|auto|always]] [--format=single-column] [FILE...]"],
  "description": "Lists directory contents. Long format shows mode, links, owner, group, size, mtime, and symlink targets. With color (default auto on a TTY), directories, symlinks, executables, and permission bits are highlighted. When stdout is captured by the shell (pipeline or **>** redirect), short format lists **one name per line** (GNU-like), so tools such as **grep** and **sort** see one entry per line.",
  "options": [
    {
      "flag": "-a",
      "meaning": "Include names starting with ."
    },
    {
      "flag": "-l",
      "meaning": "Long listing"
    },
    {
      "flag": "-1, --format=single-column, --format=vertical",
      "meaning": "One name per line (short format); same layout when stdout is piped or redirected"
    },
    {
      "flag": "--color[=never|auto|always]",
      "meaning": "ANSI colors: never, auto (TTY only), or always; plain --color is auto"
    }
  ],
  "environment": [
    "NO_COLOR — disable color even when a TTY or --color=always"
  ],
  "keywords": ["ls", "list", "directory", "dir"],
  "bareOsNotes": "Hides .bareos_empty marker like other tools.",
  "examples": [
    {
      "caption": "long + hidden",
      "code": "ls -la ~"
    },
    {
      "caption": "one per line",
      "code": "ls -1 /bin | head"
    },
    {
      "caption": "multiple paths",
      "code": "ls /bin /etc"
    }
  ]
}