Skip to main content

LS

Lists files and directories in a given path with powerful filtering and sorting options.

Common Properties​

  • Name - The custom name of the node.
  • Color - The custom color of the node.
  • Delay Before (sec) - Waits in seconds before executing the node.
  • Delay After (sec) - Waits in seconds after executing node.
  • Continue On Error - Automation will continue regardless of any error. The default value is false.

Inputs​

  • Path - string - Absolute path to the directory to list (required).
  • Ignore - array - Array of glob patterns to ignore (optional).

Options​

  • Show Hidden - bool - Show hidden files and directories (default: false).
  • Recursive - bool - List subdirectories recursively (default: false).
  • Files Only - bool - Show only files, not directories (default: false).
  • Directories Only - bool - Show only directories, not files (default: false).
  • Sort By - string - Sort entries by: Name, Size, or Modified Time (default: Name).
  • Max Depth - int - Maximum depth for recursive listing, 1 = current directory only (default: 1).

Outputs​

  • Entries - array - Array of file and directory entries. Each entry includes:
    • name - File or directory name
    • path - Absolute path
    • size - Size in bytes (0 for directories)
    • modTime - Last modification time (ISO 8601)
    • isDir - Whether this is a directory
    • permissions - Permission string (Unix format)
    • type - Entry type: "file", "directory", or "symlink"
  • Count - int - Total number of entries.
  • Total Size - int - Total size of all files in bytes (excludes directories).
  • Directory Info - object - Information about the listed directory:
    • path - Directory path
    • name - Directory name
    • modTime - Last modification time
    • permissions - Directory permissions

How It Works​

The LS node lists directory contents with flexible filtering. When executed, the node:

  1. Validates the path is absolute and exists
  2. Checks that the path is a directory
  3. Parses ignore patterns if provided
  4. Lists directory entries:
    • Non-recursive: Lists immediate children only
    • Recursive: Lists all entries up to max depth
  5. Applies filters:
    • Hidden file filter (based on name starting with .)
    • Ignore patterns (glob matching)
    • Files only / Directories only
  6. Sorts entries based on sort criteria
  7. Returns entry details and directory metadata

Requirements​

  • Valid absolute directory path
  • Read permissions on the directory
  • For recursive listing: read permissions on subdirectories

Error Handling​

The node will return specific errors in the following cases:

  • Missing path - "Path is required"
  • Relative path - "Path must be absolute"
  • Path not found - "Path not found: {{path}}"
  • Access denied - "Cannot access path: {{error}}"
  • Not a directory - "Path must be a directory"
  • Invalid ignore patterns - "Invalid ignore patterns: {{error}}"
  • Listing error - "Error listing directory: {{error}}"

Usage Examples​

List Current Directory​

Path: /home/user/documents

List with Hidden Files​

Path: /home/user/project
Show Hidden: true

List Only Files​

Path: /home/user/downloads
Files Only: true
Sort By: Size

Recursive Listing​

Path: /home/user/src
Recursive: true
Max Depth: 3

List with Ignore Patterns​

Path: /home/user/project
Ignore: ["node_modules", "*.log", ".git"]
Recursive: true

List Sorted by Time​

Path: /var/logs
Sort By: Modified Time
Files Only: true

List Directories Only​

Path: /home/user
Directories Only: true
Sort By: Name

Usage Notes​

  • All paths in output are absolute paths
  • Hidden files/directories start with a dot (.)
  • Size is always 0 for directories
  • Total Size includes only files, not directory overhead
  • Sorting always places directories before files within each group
  • Max Depth of 1 means current directory only (no recursion)
  • Ignore patterns use glob syntax (*, **, ?, etc.)
  • Symlinks are identified but not followed by default
  • Permissions use Unix format (e.g., drwxr-xr-x)

Ignore Pattern Syntax​

Ignore patterns use glob matching:

  • node_modules - Exact name match
  • *.log - All .log files
  • *.{tmp,bak} - Multiple extensions
  • test_* - Files starting with test_
  • **/*.pyc - Recursive match

Common Use Cases​

Project Exploration​

List source code directories to understand project structure.

File Management​

Find files to process, sort by size or date.

Backup Planning​

Identify directories for backup by size and date.

Cleanup Operations​

Find temporary or old files for deletion.

Build Systems​

List source files while ignoring build artifacts.

Directory Monitoring​

Track directory contents and changes over time.

Best Practices​

  • Use absolute paths always for consistency
  • Set Max Depth appropriately for recursive listings
  • Use ignore patterns to skip unnecessary directories (node_modules, .git, etc.)
  • Enable Files Only when you need to process files
  • Sort by Size to find large files
  • Sort by Time to find recent changes
  • Check permissions before attempting to access entries
  • Use with Grep/Read to process listed files

Performance Tips​

  • Avoid deep recursion on large directory trees
  • Use ignore patterns to skip large directories (node_modules, dist, build)
  • Use Files Only or Directories Only to reduce processing
  • Set appropriate Max Depth to limit search scope
  • Results are returned after complete directory scan

Comparison with Other Nodes​

  • LS vs Glob: LS lists directory contents; Glob finds files by pattern across tree
  • LS vs Shell (ls command): LS provides structured output; Shell ls gives text output
  • LS vs Read: LS lists directory; Read reads file contents