Skip to main content

​
Syntax

mkdir [-p] directory...

​
Description

The mkdir command creates one or more directories within Nash’s virtual filesystem. By default, it creates only the final directory in a path and fails if parent directories don’t exist. With the -p flag, it creates all necessary parent directories automatically.
All directories are created within Nash’s Virtual Filesystem (VFS). To create directories on the host system, you must mount a host directory with write permissions using --bind.

​
Options

​
-p
flag
Create parent directories as needed. If parent directories already exist, no error is reported. This allows creating deep directory structures in a single command.

​
Arguments

​
directory
string
required
One or more directory paths to create. Can be absolute paths (starting with /) or relative paths from the current working directory. Multiple directories can be specified separated by spaces.

​
Behavior

  1. Without -p: Creates only the final directory, fails if parent directories don’t exist
  2. With -p: Creates all parent directories in the path automatically
  3. Multiple directories: Can create several directories in one command
  4. Existing directories: With -p, silently succeeds if directory already exists; without -p, may report error
  5. Path resolution: Relative paths are resolved from current working directory

​
Examples

​
Create a single directory

user@nash:/home/user$ mkdir projects
user@nash:/home/user$ ls
Desktop/  Documents/  Downloads/  projects/  welcome.txt

​
Create multiple directories

user@nash:/home/user$ mkdir docs videos music
user@nash:/home/user$ ls
Desktop/  Documents/  Downloads/  docs/  music/  videos/  welcome.txt

​
Create nested directories with -p

user@nash:/home/user$ mkdir -p projects/nash/src/builtins
user@nash:/home/user$ tree projects
projects
└── nash/
    └── src/
        └── builtins/

3 directories, 0 files

​
Create directory with absolute path

user@nash:/home/user$ mkdir /tmp/workdir
user@nash:/home/user$ ls /tmp
workdir/

​
Create multiple nested paths

user@nash:/home/user$ mkdir -p project/src project/tests project/docs
user@nash:/home/user$ tree project
project
├── docs/
├── src/
└── tests/

3 directories, 0 files

​
Use in command chains

user@nash:/home/user$ mkdir build && cd build && pwd
/home/user/build

​
Create and populate directory

user@nash:/home/user$ mkdir reports && cd reports && touch q1.txt q2.txt
user@nash:/home/user/reports$ ls
q1.txt  q2.txt

​
Error Handling

​
Missing operand

user@nash:/home/user$ mkdir
mkdir: missing operand
At least one directory path must be provided to mkdir.

​
Parent directory doesn’t exist (without -p)

user@nash:/home/user$ mkdir deep/nested/dir
Error: parent directory does not exist
Solution: Use the -p flag: 
user@nash:/home/user$ mkdir -p deep/nested/dir
user@nash:/home/user$ tree deep
deep
└── nested/
    └── dir/

2 directories, 0 files

​
Directory already exists

With -p flag, this silently succeeds: 
user@nash:/home/user$ mkdir -p projects
user@nash:/home/user$ mkdir -p projects
# No error - succeeds silently

​
Invalid path

user@nash:/home/user$ touch file.txt
user@nash:/home/user$ mkdir file.txt/subdir
Error: cannot create directory
Cannot create a directory inside a file or through a non-directory path.

​
VFS Integration

​
Creating directories in mounted volumes

When working with mounted host directories (read-write), mkdir creates real directories on the host: 
# Start Nash with a read-write mount
$ nash --bind ./myproject:/project

user@nash:/home/user$ cd /project
user@nash:/project$ mkdir src tests
user@nash:/project$ ls
src/  tests/

# These directories now exist in host ./myproject/ directory

​
Read-only mounts

Attempting to create directories in read-only mounted paths will fail: 
$ nash --bind-ro ./readonly:/data

user@nash:/home/user$ mkdir /data/newdir
Error: cannot create directory (read-only filesystem)
Directories cannot be created in read-only mounted paths. Use --bind instead of --bind-ro if you need write access.

​
Common Patterns

​
Project scaffolding

user@nash:/home/user$ mkdir -p myapp/src myapp/tests myapp/docs myapp/config
user@nash:/home/user$ tree myapp
myapp
├── config/
├── docs/
├── src/
└── tests/

4 directories, 0 files

​
Temporary workspace

user@nash:/home/user$ mkdir -p /tmp/workspace && cd /tmp/workspace
user@nash:/tmp/workspace$ pwd
/tmp/workspace

​
Date-based directories

user@nash:/home/user$ mkdir -p logs/2026/03/06
user@nash:/home/user$ tree logs
logs
└── 2026/
    └── 03/
        └── 06/

3 directories, 0 files

​
Conditional directory creation

user@nash:/home/user$ test -d backup || mkdir backup
user@nash:/home/user$ ls
Desktop/  Documents/  Downloads/  backup/  welcome.txt

​
Combining with Other Commands

​
With cd to navigate into new directory

user@nash:/home/user$ mkdir workspace && cd workspace && pwd
/home/user/workspace

​
With find to verify creation

user@nash:/home/user$ mkdir -p a/b/c a/b/d a/e
user@nash:/home/user$ find a -type d
a
a/b
a/b/c
a/b/d
a/e

​
With tree to visualize structure

user@nash:/home/user$ mkdir -p project/{src,tests,docs}
user@nash:/home/user$ tree project
project
├── docs/
├── src/
└── tests/

3 directories, 0 files

​
With touch to create files

user@nash:/home/user$ mkdir data && touch data/file1.txt data/file2.txt
user@nash:/home/user$ ls data
file1.txt  file2.txt

​
Exit Codes

  • 0 - Success: all directories created successfully
  • 1 - Error: missing operand or directory creation failed
  • cd - Change to the newly created directory
  • rmdir - Remove empty directories (use rm -r for non-empty)
  • ls - List directory contents
  • tree - Display directory structure
  • pwd - Show current directory
  • find - Search for directories with -type d

​
Implementation Details

The mkdir command is implemented in /home/daytona/workspace/source/src/builtins/mkdir.rs:9-35. Key implementation notes:
  • Parses arguments to separate -p flag from directory paths
  • Without -p: calls vfs.mkdir() which creates only the final directory
  • With -p: calls vfs.mkdir_p() which creates all parent directories
  • All paths are resolved relative to current working directory using VfsPath::join()
  • Returns error if no directory paths are provided
  • Processes all directories even if some fail (doesn’t stop at first error)

​
Comparison to Traditional Unix mkdir

Nash’s mkdir implements the most common functionality:
FeatureNash mkdirUnix mkdir
-p flag✓ Supported✓ Supported
-m mode✗ Not supported✓ Set permissions
-v verbose✗ Not supported✓ Print created directories
Multiple directories✓ Supported✓ Supported
PermissionsN/A (VFS has no permissions)Configurable
Nash’s VFS doesn’t implement Unix file permissions, so the -m flag for setting directory modes is not needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us