Ignoring Files

By default, Storyteller tracks all changes to the files and directories under the topmost open directory, called the Storyteller project directory. Sometimes, there are changes that one doesn't care to track. For example, the binaries that get generated from a compiler or a long log file.

A file that is placed in the Storyteller project directory with the name st-ignore.json will be used to tell Storyteller which files and directories to ignore. It can specify files with a particular extension, files with a particular name, and directories with a particular path to ignore.


st-ignore.json files are similar in spirit to git's .gitignore files. However, the syntax is different than git's syntax. In particular, no wildcards are allowed. st-ignore.json files are ordinary JSON files with the following format:

    "ignoredFileExtensions": [".obj", ".o"],
    "ignoredFiles": ["server.log", "sales.db"],
    "ignoredDirectories": ["/bin", "/tests/docs", "/.git"]

Tip: Include all three of these properties in the object even if you are not using them. Make sure to include an empty JSON array [] for any property that you are not using.


The property ignoredFileExtensions specifies an array of file extensions that will be ignored. The dots in the strings are required. All changes to files with any one of these extensions will be ignored by Storyteller. This is ideal for files that get generated by a tool like an object file or a bytecode file.


The property ignoredFiles specifies an array of file names that will be ignored. No part of path leading up to the file name should be included. All changes to files with any one of these names anywhere in the project directory will be ignored by Storyteller.

Tip: The file st-ignore.json is always ignored so there is no need to include it.


The property ignoredDirectories specifies an array of paths to directories that will be ignored. All changes to files and subdirectories with any one of these paths will be ignored by Storyteller. The entries must be relative paths from the Storyteller project directory. The strings in the array must start with a leading /.

For example, if the Storyteller project that is being tracked is at the full path /users/markm/my-code on a machine then the rule specified, "/bin", says to ignore all changes to the directory called bin inside the open Storyteller directory. In other words, ignore all changes that happen in /users/markm/my-code/bin and its subdirectories.

Tip: The hidden directory .storyteller is always ignored.

Questions? Comments? Corrections? Contact the BDFL