ls
List files and directories within a repository to inspect project structure and contents. Supports branch isolation for secure file browsing in build environments.
Instructions
List files and directories in a repository. Limited to paths within the repository to prevent path traversal. If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| args | No | Arguments to pass to ls (e.g., '-la', '-lh build/') | |
| repo | Yes | Repository name (required) | |
| branch | No | Git branch name (optional). If provided, uses isolated worktree. |
Implementation Reference
- src/server.py:521-537 (handler)The handler function that implements the core logic of the 'ls' tool: parses input arguments, validates them, constructs the 'ls' shell command, executes it within the specified repository worktree (handling branch-specific isolation and locking), and returns the output.
async def handle_ls(self, args: Dict[str, Any]) -> List[TextContent]: """Handle ls command""" repo = args.get("repo") branch = args.get("branch") ls_args = args.get("args", "") # Validate arguments validate_ls_args(ls_args) # Build command cmd = ["ls"] if ls_args: cmd.extend(shlex.split(ls_args)) # Execute in appropriate worktree with locking result = await self.execute_in_worktree(repo, branch, cmd) return [TextContent(type="text", text=result)] - src/server.py:372-395 (schema)The tool schema definition returned by list_tools(), including name, description, and JSON inputSchema specifying required 'repo' and optional 'args'/'branch' parameters.
Tool( name="ls", description="List files and directories in a repository. " "Limited to paths within the repository to prevent path traversal. " "If branch is specified, creates/uses a hidden worktree (.repo@branch) for isolation.", inputSchema={ "type": "object", "properties": { "args": { "type": "string", "description": "Arguments to pass to ls (e.g., '-la', '-lh build/')" }, "repo": { "type": "string", "description": "Repository name (required)" }, "branch": { "type": "string", "description": "Git branch name (optional). If provided, uses isolated worktree." } }, "required": ["repo"] } ), - src/server.py:459-460 (registration)Tool dispatch/registration in the central execute_tool() method, which routes 'ls' calls to the handle_ls handler.
elif name == "ls": return await self.handle_ls(arguments) - src/validators.py:141-171 (helper)Helper function validate_ls_args() that checks 'ls' arguments for dangerous patterns (path traversal, shell injection), validates flags, and sanitizes paths to prevent escapes.
def validate_ls_args(args: str) -> None: """ Validate ls command arguments Args: args: Ls command arguments Raises: ValueError: If arguments contain dangerous patterns """ if not args: return # Empty args is fine (will list current directory) # Check for dangerous patterns if contains_dangerous_pattern(args): raise ValueError(f"Ls arguments contain dangerous patterns: {args}") # Parse arguments to validate paths parts = args.split() for part in parts: # Skip flags (starting with -) if part.startswith('-'): # Validate flag is reasonable if not re.match(r'^-[a-zA-Z]+$', part): raise ValueError(f"Invalid ls flag: {part}") continue # Validate paths validate_path(part)