How to Configure cd_on_quit for Shell Integration in Superfile

Set cd_on_quit = true in your Superfile configuration and source the appropriate wrapper script for Bash, Zsh, Fish, or PowerShell to enable automatic directory changing when you exit the file manager.

Superfile is a modern terminal file manager written in Go that supports seamless shell integration through its cd_on_quit functionality. When enabled, this feature captures the last directory you were browsing and passes it back to your shell upon exit. To configure cd_on_quit for shell integration in Superfile, you must toggle a configuration flag and install a shell-specific wrapper that handles the directory handoff.

Enable cd_on_quit in Superfile Configuration

The cd_on_quit behavior is controlled by a boolean setting defined in the configuration type struct at src/internal/common/config_type.go. To activate it, modify your configuration file (src/superfile_config/config.toml in the source repository) to set the flag to true:

#-- cd on quit

# Should we cd the shell to the last directory open in superfile when the

# program exits? 

cd_on_quit = true

When this option is enabled, Superfile writes the current directory path to a temporary file named lastdir before exiting. On Linux, this file is stored at $XDG_STATE_HOME/superfile/lastdir, while on macOS it uses $HOME/Library/Application Support/superfile/lastdir.

Bash and Zsh Setup

For Bash and Zsh, use the wrapper script located at cd_on_quit/cd_on_quit.sh. This script exports the SPF_LAST_DIR environment variable pointing to the lastdir file location, then wraps the spf command to change directories after Superfile exits.

Add the following to your ~/.bashrc or ~/.zshrc:

# Enable Superfile cd-on-quit integration

source "$HOME/.config/superfile/cd_on_quit.sh"

After reloading your shell configuration, use the spf command to launch Superfile instead of calling the binary directly.

Fish Shell Setup

Fish users should source cd_on_quit/cd_on_quit.fish, which sets the spf_last_dir variable and provides equivalent functionality using Fish syntax.

Add to ~/.config/fish/config.fish:

# Enable Superfile cd-on-quit integration

source $HOME/.config/superfile/cd_on_quit.fish

This wrapper defines a spf function that runs Superfile, sources the saved directory from the lastdir file, and removes the temporary file automatically.

PowerShell Setup

Windows PowerShell integration uses cd_on_quit/cd_on_quit.ps1. This script expects Superfile to be installed at %LOCALAPPDATA%\Programs\superfile\spf.exe and handles the directory change via Invoke-Expression.

Dot-source the script in your PowerShell profile:

# Enable Superfile cd-on-quit integration

. $HOME\Documents\PowerShell\cd_on_quit.ps1

After reloading your profile, the spf function will be available and will execute the directory change when you quit Superfile.

How cd_on_quit Works Internally

The integration relies on an internal flag handled in src/cmd/main.go. When Superfile starts with the --lastdir option (which the wrappers automatically append), it monitors the current directory. Upon exit, it writes the path to the lastdir file in your state directory. The wrapper script then reads this file, executes cd to that path, and deletes the temporary file.

The process flow is:

1. You type spf in your shell
2. The wrapper sets the SPF_LAST_DIR (or shell equivalent) variable and launches Superfile with --lastdir
3. You navigate and press q to quit
4. Superfile writes the final directory to the lastdir file
5. The wrapper sources that path and changes your shell's working directory
6. The temporary file is removed

Summary

• Enable the feature by setting cd_on_quit = true in the configuration, as defined in src/internal/common/config_type.go and shown in src/superfile_config/config.toml
• Install the wrapper by sourcing the appropriate script from cd_on_quit/cd_on_quit.sh (Bash/Zsh), cd_on_quit/cd_on_quit.fish (Fish), or cd_on_quit/cd_on_quit.ps1 (PowerShell) in your shell's startup file
• Use the spf command instead of running the Superfile binary directly to ensure the directory handoff occurs
• Cross-platform support works on Linux, macOS, and Windows through XDG-compliant paths or %LOCALAPPDATA%

Frequently Asked Questions

Where do I place the cd_on_quit wrapper scripts on my system?

Copy the appropriate script from the Superfile repository's cd_on_quit/ directory to a permanent location such as ~/.config/superfile/, then source it from your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish). The scripts are located at cd_on_quit/cd_on_quit.sh for Bash/Zsh, cd_on_quit/cd_on_quit.fish for Fish, and cd_on_quit/cd_on_quit.ps1 for PowerShell.

Why must I use the spf command instead of superfile?

The wrapper scripts define a function or alias named spf that sets the necessary environment variables (like SPF_LAST_DIR), launches Superfile with the internal --lastdir flag handled in src/cmd/main.go, and processes the lastdir file after exit. Running the raw superfile binary bypasses this wrapper logic, preventing the directory change from occurring.

Can I customize the location of the lastdir file?

The path is determined by the SPF_LAST_DIR environment variable in Bash/Zsh or spf_last_dir in Fish, which defaults to $XDG_STATE_HOME/superfile/lastdir on Linux and $HOME/Library/Application Support/superfile/lastdir on macOS. You can override this by setting the variable before sourcing the wrapper script, though the standard locations follow XDG Base Directory specifications.

Does cd_on_quit work on Windows with PowerShell?

Yes, the cd_on_quit.ps1 script provides full support for Windows PowerShell and PowerShell Core. It uses %LOCALAPPDATA%\Programs\superfile\spf.exe as the binary path and Invoke-Expression to change directories, removing the temporary file after execution just like the Unix shell wrappers.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}