FDF Script Syntax Reference

This is the complete reference for .fdf script syntax. Use these commands to define how your dotfiles are deployed.

Basic Structure

An .fdf script is a plain text file containing commands, one per line. Comments start with # and empty lines are ignored.

# This is a comment
CONFIG default_dir = dotfiles

PUT .bashrc IN ~/.bashrc
PUT .vimrc IN ~/.vimrc

END FETCH

Configuration

Use CONFIG to set options that affect how the script runs. Place these at the top of your script.

CONFIG

Sets a configuration value.

CONFIG <key> = <value>

Available keys:

Examples:

CONFIG default_dir = config
CONFIG select_from_root = true

File Operations

PUT

Copy a file from your repository to a destination path.

PUT <source> IN <destination>

Examples:

PUT .bashrc IN ~/.bashrc
PUT config/nvim/init.lua IN ~/.config/nvim/init.lua
PUT themes/dark.toml IN ~/.config/alacritty/colors.toml

The IN keyword is required. Paths starting with ~ are expanded to your home directory.

LINK

Create a symbolic link instead of copying. Useful when you want changes to sync automatically.

LINK <source> TO <destination>

Examples:

LINK .gitconfig TO ~/.gitconfig
LINK scripts/backup.sh TO ~/bin/backup

COPY

Alternative syntax for copying files (same as PUT).

COPY <source> TO <destination>

Examples:

COPY wallpaper.png TO ~/Pictures/wallpaper.png

Directory Operations

MKDIR

Create a directory if it doesn't exist.

MKDIR <path>

Examples:

MKDIR ~/.config/nvim
MKDIR ~/.local/bin
MKDIR ~/Projects

This is useful before placing files in directories that may not exist on a fresh system.

Shell Commands

RUN

Execute a shell command directly.

RUN <command>

Examples:

RUN sudo pacman -S --noconfirm neovim
RUN chmod +x ~/.local/bin/my-script
RUN git clone https://github.com/tmux-plugins/tpm ~/.tmux/plugins/tpm

Use this for installing dependencies, setting permissions, or running setup scripts.

EXECUTE

Execute a command with quoted syntax (useful for complex commands).

EXECUTE "<command>"

Examples:

EXECUTE "curl -fsSL https://example.com/install.sh | bash"
EXECUTE "echo 'source ~/.bashrc' >> ~/.bash_profile"

Output

ECHO

Print a message to the terminal during execution.

ECHO "<message>"

Examples:

ECHO "Installing dependencies..."
ECHO "Setup complete! Please restart your terminal."
ECHO "Don't forget to run: source ~/.bashrc"

Useful for providing feedback or instructions to the user.

Script Termination

END FETCH

Marks the end of the script. This should be the last line.

END FETCH

While not strictly required, including END FETCH is recommended for clarity and to ensure the parser doesn't expect more commands.

Complete Example

Here's a full example for setting up a Hyprland desktop environment:

# Hyprland dotfiles setup
CONFIG default_dir = dotfiles

# Install dependencies
RUN sudo pacman -S --noconfirm hyprland waybar wofi kitty

# Create config directories
MKDIR ~/.config/hypr
MKDIR ~/.config/waybar
MKDIR ~/.config/kitty

# Place config files
PUT hypr/hyprland.conf IN ~/.config/hypr/hyprland.conf
PUT waybar/config IN ~/.config/waybar/config
PUT waybar/style.css IN ~/.config/waybar/style.css
PUT kitty/kitty.conf IN ~/.config/kitty/kitty.conf

# Shell config
PUT .bashrc IN ~/.bashrc
PUT .bash_aliases IN ~/.bash_aliases

# Scripts
MKDIR ~/.local/bin
PUT scripts/screenshot.sh IN ~/.local/bin/screenshot
RUN chmod +x ~/.local/bin/screenshot

ECHO "Hyprland setup complete!"
ECHO "Reboot and select Hyprland from your display manager."

END FETCH

Tips

1. Order matters - Commands are executed top to bottom
2. Use MKDIR first - Create directories before putting files in them
3. Comments are helpful - Document what each section does
4. Test with dry run - Use fdf -d to preview changes before applying

Validation

Use the Syntax Validator to check your scripts for errors before deploying.