FoxTrot hidden preferences

Here are some commands you can type in It is suggested to quit FoxTrot before typing them.
Note: Starting with version 7.1, hidden preferences should be set for the domain com.ctmdev.FoxTrotShared. For previous versions, please use instead com.ctmdev.FoxTrot for FoxTrot Personal; or com.ctmdev.FoxTrotPro for FoxTrot Professional; or com.ctmdev.FoxTrotAdmin for FoxTrot Search Admin.
To reset a specific preference to its default value, type defaults delete com.ctmdev.FoxTrotShared PreferenceName

We recommend using the Prefs Editor application, if you don't like typing commands in

Indexing specific filetypes:

Disabling Indexing Specific File Types
  • to disable indexing the contents of a specific file type (replace extension by the actual filename extension); you will then need to rebuild your index:
    • defaults write com.ctmdev.FoxTrotShared Aliases -array-add "{type='extension'; as='';}"
Aliasing File Types
  • to index the contents of a specific file type as if it was another file type (replace overriddenExtension and overridingExtension by the actual filename extensions):
    • defaults write com.ctmdev.FoxTrotShared Aliases -array-add "{type='overriddenExtension'; as='overridingExtension';}"
Disabling or Aliasing Files Types with Headers
  • to disable indexing, or override the filename extension, for files with given extension only when their contents starts with a specific hexadecimal header:
    • defaults write com.ctmdev.FoxTrotShared Aliases -array-add "{type='extension'; headers=(<hexadecimal header>); as='';}"
  • you may also specify multiple possible headers:
    • defaults write com.ctmdev.FoxTrotShared Aliases -array-add "{type='extension'; headers=(<header 1>,<header 2>,<header 3>); as='';}"
  • to reset (you should then launch FoxTrot and quit it again, before altering this setting again, with defaults write ...):
    • defaults delete com.ctmdev.FoxTrotShared Aliases
  • Note that you can specify Uniform Type Identifiers (UTI), or HFS file types, instead of extensions. For exemple, for plain text files, you can use either txt, .txt, public.plain-text, or <TEXT>.
Indexing HTML files (FoxTrot 7.5 and later)
  • to index specific HTML files using Gumbo, instead of Spotlight’s metadata importer:
    • xattr -w com.ctmdev.foxtrot.extractor gumbo [file [file…]]
  • to index specific HTML files using Spotlight’s metadata importer, instead of Gumbo, when Gumbo is preferred for all files:
    • xattr -w com.ctmdev.foxtrot.extractor spotlight [file [file…]]
  • to reset the default for specific HTML files:
    • xattr -d com.ctmdev.foxtrot.extractor [file [file…]]
Indexing large plain text or HTML files (FoxTrot 7.1 and later)

Due to a limitation of Spotlight's metadata importers, only the first 10 MB of each file is indexed by default. You can modify (or completely remove) this limit for plain text files (.txt, .log etc). This setting will also apply to HTML files if you choose to use Gumbo as an alternative to Spotlight's importer for HTML files (version 7.5.4 or later).

  • to change the size limit of plain text files to n megabytes (n may be larger than 10):
    • defaults write com.ctmdev.FoxTrotShared PlainTextFileLimitMB -int n
  • to completely remove the limit:
    • defaults write com.ctmdev.FoxTrotShared PlainTextFileLimitMB -int 0
  • to reset the default limit:
    • defaults delete com.ctmdev.FoxTrotShared PlainTextFileLimitMB
Changing default character set encoding for text files (FoxTrot 7.1 and later)

Text files created by or some other macOS apps use the extended attribute to specify the character set encoding used; however many other text files (downloaded files, log files etc) do not specify it, and do not use a unicode byte order mark (BOM) either. By default, FoxTrot uses Spotlight's metadata importer to process text files, which may choose an incorrect encoding for those files. You can change the list of preferred encodings to use when there is no extended attribute or BOM. If a file can't be processed using the first encoding, the second one is used, etc.

  • to change character set encodings to use for plain text files:
    • defaults write com.ctmdev.FoxTrotShared PlainTextPreferredEncodings 'encodings'

'encodings' is a quoted, comma-separated list of encodings; for example:

  • if you have some Windows-Latin files: 'utf-8,windows-1252,macintosh'
  • if you have no Windows-Latin file (or much more Mac-Roman files than Windows-Latin files); but have some ISO-Latin files: 'utf-8,iso-8859-1,macintosh'
  • if you have no Windows-Latin nor ISO-Latin files; but have some Mac-Roman files: 'utf-8,macintosh'


  • utf-8 should almost always be the first encoding in the list (as trying to decode any other encoding as UTF-8 will usually fail: many byte sequences are invalid in UTF-8)
  • no other encoding should be specified after macintosh (as trying to decode any other encoding as Mac-Roman will never fail: all byte sequences are valid in Mac-Roman and most other legacy Mac encodings)
  • specifying both iso-8859-1 and windows-1252 is usually useless (the second one being a superset of the first one). If you have some windows-1252 files for sure, or have no other encodings than utf-8, iso-8859-1 and possibly windows-1252, then use utf8,windows-1252; if you have no (or very few) windows-1252 files, but have some other encodings (legacy Mac encodings, non western european encodings…), use utf-8,iso-8859-1, followed by the other encodings

Other indexing options:

Index Compression
  • to enable compressing PDF files, when storing a copy of the files in the index (note that many PDF files are already compressed, so re-compressing them in FoxTrot will use more CPU, without reducing the index size significantly):
    • defaults write com.ctmdev.FoxTrotShared CompressPDF -bool YES
  • to change the compression level of stored textual contents:
    • defaults write com.ctmdev.FoxTrotShared ContentZstdLevel -int level
    • with level being an integer between 1 (fastest) and 22 (most compressed). Default level is 5.
  • to change the compression level of stored documents:
    • defaults write com.ctmdev.FoxTrotShared DocumentZstdLevel -int level
    • with level being an integer between 1 (fastest) and 22 (most compressed). Default level is 5.
  • to change the compression dictionary used to compress stored textual contents, run the shell script Set FoxTrot Content Compression Dictionary.command in
Indexing Finder Comments, Finder Tags, OpenMeta Tags, and extended attributes
  • to disable indexing of Finder comments (aka Spotlight comments), Finder tags, and metadata stored as HFS+/APFS extended attributes:
    • defaults write com.ctmdev.FoxTrotShared SkipFinderComments -bool YES
    • Note: this this will also disable the per-file choice of using Xpdf or Gumbo to process PDF and HTML files
  • to enable indexing of OpenMeta tags, in addition to standard Finder Tags:
    • defaults write com.ctmdev.FoxTrotShared HonorOpenMetaTags -bool YES
Language Identification
  • to disable language identification:
    • defaults write com.ctmdev.FoxTrotShared RestrictLanguageIdentification ""
    • to restrict language identification to some languages: defaults write com.ctmdev.FoxTrotShared RestrictLanguageIdentification "fr en"
  • to use the Natural Language framework for language identification, on macOS 10.14 and later (slower indexing, but may produce better identification):
    • defaults write com.ctmdev.FoxTrotShared UseNaturalLanguageIdentification -bool YES
Multicore Processing
  • to set the maximum number of concurrent index updates (the default is one by CPU core):
    • defaults write com.ctmdev.FoxTrotShared MaxConcurrentIndexUpdates -int n
  • to manually define the maximum number of concurrent extractor processes, for each index (the default is automatic and depends on the number of CPU cores):
    • defaults write com.ctmdev.FoxTrotShared ExtractorCount -int n
  • to enable benchmarking index rebuild, the next time you launch FoxTrot Pro:
    • defaults write com.ctmdev.FoxTrotShared Benchmark yes
  • to enable benchmarking index rebuild, permanently:
    • defaults write com.ctmdev.FoxTrotShared Benchmark permanent
Attributes Modification Date
  • to ignore the attributes modification date when determining if a files has changed and needs to be updated (so changing the Spotlight comments or Finder label won't mark the file for update), set IgnoreAttributesModificationDate to true in the Config file (in the Finder, use the "Show package content" contextual menu on the index file, located in {home}/Library/FoxTrot):
    • <ignoreattributesmodificationdate>true</ignoreattributesmodificationdate>
Automatic Compaction
  • to disable automatic-compaction of the indices:
    • defaults write com.ctmdev.FoxTrotShared DisableAutoCompact -bool YES
Indexing of the relative path (or full path) of the parent folder of each file
  • The name of the folder containing a file is normally indexed as part of the “other metadata”, allowing to find files directly in this folder by searching the folder name. Instead, you may want to index the relative path of this folder (i.e. the full path of this folder, stripped from the path of the indexed folder), so you can find all files at any depth inside a folder. For example, if the indexed folder is “/Users/john/Documents”, and the file is “/Users/john/Documents/Stuff/Project/data.pdf”, then the relative path of the parent folder is “Stuff/Project”). To do so (this requires rebuilding the index afterwards):
    • defaults write com.ctmdev.FoxTrotShared UseRelativePathForParentFolder -bool YES
  • You may want to index the full path of the parent folder, instead of its name or relative path (for example, “/Users/john/Documents/Stuff/Project”). To do so, make sure to clear the above UseRelativePathForParentFolder preference, then (this requires rebuilding the index afterwards):
    • defaults write com.ctmdev.FoxTrotShared UseFullPathForParentFolder -bool YES
Skipping some folders at indexing time
  • In addition to designating some folders in the “skipping these subfolders” list (in the “indexed data” tab of the “manage indices” window), yo can add an empty file named “.noindex” in each folder you don’t want FoxTrot to index. You may have to show invisble files in the Finder (press the keys command-option-dot) in order to create, rename or delete such a file, as the Finder does not show files or folder whose name starts with a dot. Folders whose name ends with “.noindex” will also be skipped.
  • With version 8, you can also define custom regular expressions to specify some other files or folders to skip. You can either use a single regular expression (define SkipPathRegex as a string) or multiple ones (define SkipPathRegex as an array of strings). To avoid incorrect parsing when using the defaults command, it is suggested to quote the regular expression between single quotes ('), and to prepend any string with a "-string" argument. The regular expression is applied to the full path, and a file or folder is skipped if its path contains the regex; use a leading ^ and / or a trailing $ if the regex should be found at the beginning / ending of the path.
    • to skip any folder whose name is exactly "cache" or "meta" (case sensitive), use one of these commands:
      • defaults write com.ctmdev.FoxTrotShared SkipPathRegex -string '/(cache|meta)$'
      • defaults write com.ctmdev.FoxTrotShared SkipPathRegex -array -string '/cache$' -string '/meta$'
    • to do the same only at any depth inside a folder whose name ends with ".repo", use one of these commands:
      • defaults write com.ctmdev.FoxTrotShared SkipPathRegex -string '\.repo/(.*/)?(cache|meta)$'
      • defaults write com.ctmdev.FoxTrotShared SkipPathRegex -array -string '\.repo/(.*/)?cache$' -string '\.repo/(.*/)?meta$'
    • FoxTrot Personal does not handle regular expressions, and uses simple patterns instead (with a leading and/or trailing * wildcard). Likewise, if the regular expression syntax is invalid, the string is then used as simple pattern on FoxTrot Pro. Note that the pattern, like the regex, is applied to the full path (and not to the folder name), so the pattern will typically be something like */cache for an exact match, or *cache* for a substring match.
    • We suggest using regex101 to validate regular expressions syntax, and Prefs Editor instead of the command line defaults to enter regular expressions.


Typo corrections
  • to customize suggestion of mistyped words:
    • defaults write com.ctmdev.FoxTrotShared AutocompleteSuggestMaxEditDistance -int n
    • Default value is n = 2 (when typo corrections are enabled in the preferences). You can set it to n = 1 to suggest fewer words, or n = 3 to suggest more words.
  • to change the precedence order for suggestions depending on the number of typos:
    • defaults write com.ctmdev.FoxTrotShared AutocompleteDistanceRankFactor -float value
    • with value being a floating point value. The default value is 100. Lower values will increase precedence for words with typos (versus completion of partially typed words), and higher values will decrease it.
Ignoring Other Metadata
  • to enable ignoring "other metadata" when searching "any metadata or filename":
    • defaults write com.ctmdev.FoxTrotShared IgnoreOtherMetadata -bool YES
Multiple Strings Separator
  • to change the multiple strings separator, used in search filters:
    • defaults write com.ctmdev.FoxTrotShared StringSeparator "separator"
    • the default separator is , which is the “em dash” character (U+2014), and it can be typed on a qwerty keyboard, with the option shift “-” combination (do not use the “-” key from the numeric keypad). separator can be any unicode single or multi-character string; it is recommended to enclose it between straight quotes in the terminal command.
Default search criteria
  • When launching FoxTrot, or opening a new search window or search tab, FoxTrot re-uses the last search criterion used. With FoxTrot Professional, if instead you prefer always using the search template set as “system menu search template”:
    • defaults write com.ctmdev.FoxTrotShared AlwaysUseSystemMenuTemplate -bool YES

Displaying found documents, and thumbnails of found documents:

Cache Duration
  • the contents of large documents is kept in a preview cache to speed up the highlight of found words in the preview (when the same document is viewed multiple times). When using the thumbnails view, thumbnails of complex files are also stored in a thumbnail cache. By default, documents and thumbnails are kept in the cache during 30 days, to prevent wasting disk space; to change this duration:
    • defaults write com.ctmdev.FoxTrotShared RemoveFromPreviewCacheAfterDays -int n
    • you can manually clear the cache from the preferences
PDF Multicore Previewing
  • PDF files must be prepared in order to highlight found occurrences. This preparation can take up to a minute or even more, for large files (i.e. complete books). Once a file has been prepared, the preview cache stores the prepared data, so the same document won't need to be prepared again until this cache is cleared or pruned. This preparation normally takes advantage of multi-core CPUs, however this is disabled on macOS 10.15 and later, as it is actually much slower due to an Apple bug. To either force multi-core preparation on 10.15 and later, or to disable it on 10.14 and earlier, or to set the maximum number of CPU cores to use, or to restore the default behavior:
    • defaults write com.ctmdev.FoxTrotShared MulticorePDFPreview -bool YES
    • defaults write com.ctmdev.FoxTrotShared MulticorePDFPreview -bool NO
    • defaults write com.ctmdev.FoxTrotShared MulticorePDFPreview -int n
    • defaults delete com.ctmdev.FoxTrotShared MulticorePDFPreview
Length of document excerpts (FoxTrot Pro only; version 7.5.1 or later)

FoxTrot Pro displays an excerpt of the content of each found document. The excerpt consists of a number of words surrounding the found words. The number of words in the excerpt is automatically adjusted according to the layout of the search results list, so that the excerpt is as relevant as possible. However, depending of the language, or of the type of documents, you may wish to increase or decrease this number of words, so that the excerpt uses all the available screen space without being truncated.

  • you can either change the average number of characters of a word. The default value is 4.25. If you increase this value, excerpts will contain less words:
    • defaults write com.ctmdev.FoxTrotShared ExcerptsAverageWordLength -float length
  • or you can define an arbitrary number of words; in this case the layout of the search results list won’t matter:
    • defaults write com.ctmdev.FoxTrotShared ExcerptsLengthInWords -int n


Network Compression
  • to disable compression of the network connections (do this on the client side):
    • defaults write com.ctmdev.FoxTrotShared DisableCompression -bool YES
First Aid Window
  • to force displaying FoxTrot First Aid Window the next time FoxTrot is launched (may be necessary if pressing the command and option keys does not work):
    • defaults write com.ctmdev.FoxTrotShared ShowFirstAidOnStartup -bool YES
Server Certificates
  • to disable verification of the server certificate, when connecting to a FoxTrot Server (which is normally required only when connecting to a FoxTrot Server by specifying its hostname, and not for servers discovered automatically on the local network with Bonjour):
    • defaults write com.ctmdev.FoxTrotShared DisableServerCertificateVerification -bool YES
User Interface Preferences
  • to use old style tabs:
    • defaults write com.ctmdev.FoxTrotShared TabStyle Card
  • to change the duration of the animation of the categorization pane:
    • defaults write com.ctmdev.FoxTrotShared CategoriesAnimationDuration -float duration
    • with duration being 0 to disable the animation, or the duration is seconds. The default 1.0.

Advanced logging:

Logging of Indices Startup
  • to enable detailed logging of indices startup (to debug error 999, for example):
    • defaults write com.ctmdev.FoxTrotShared LogLaunchSource -bool YES
    • These messages will be logged in {home}/Library/FoxTrot/FoxTrotStarter.log
Logging of Registration Code Network Verification
  • to enable logging of registration code network verification:
    • defaults write com.ctmdev.FoxTrotShared LogNetworkRegistration -bool YES
    • To see these logged messages, launch (from /Applications/Utilities), select "system.log" in the left pane, type Network Registration in the toolbar search field.
Logging of Bonjour Shared Indices
  • to enable logging of Bonjour FoxTrot Server / FoxTrot Pro shared indices:
    • defaults write com.ctmdev.FoxTrotShared LogNetworkServices -bool YES
    • To see these logged messages, launch (from /Applications/Utilities), select "system.log" in the left pane, type "Network Services" in the toolbar search field.
Logging All Queries
  • to enable logging all queries in the "FoxTrotIndexer.log" file, set LogQuery to true in the Config file (in the Finder, use the "Show package content" contextual menu on the index file, located in {home}/Library/FoxTrot):
    • <logquery>true</logquery>
    • These messages will be logged in {home}/Library/FoxTrot/FoxTrotIndexer.log