FoxTrot hidden preferences
Here are some commands you can type in Terminal.app. 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 Terminal.app.
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…]]
- when using Gumbo, to index the link URLs as part of the content (instead of as part of other metadata) [FoxTrot 8.0.4]:
defaults write com.ctmdev.FoxTrotShared GumboMarkdownLinks -bool YES
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 TextEdit.app or some other macOS apps use the com.apple.TextEncoding 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'
Note:
- 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 Terminal.app
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
totrue
in theConfig
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 specifying some folders in the “skipping these subfolders” list (in the “indexed data” tab of the “manage indices” window), you 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 (defineSkipPathRegex
as an array of strings). To avoid incorrect parsing when using thedefaults
command, it is recommended to enclose the regular expression in single quotes ('), and to prefix each 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$'
- The
SkipPathRegex
preference applies to all your indices; with version 8.0.4 or later, to apply it to a single index, append the name of the index to the preference key (and enclose it in straight quotes), e.g. `'SkipPathRegex Main Index'
for an index named “Main Index” - 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.
- to skip any folder whose name is exactly “cache” or “meta” (case-sensitive), use one of these commands:
Indexing the contents of some file paths only
- In addition to specifying only some file types in the “Index contents of files” list (in the “indexed data” tab of the “manage indices” window), with version 8.0.4 or later, you can also define custom regular expressions to specify some additional conditions for indexing file contents. You can use either a single regular expression (define
OnlyIndexContentsPathRegex
as a string) or multiple ones (defineOnlyIndexContentsPathRegex
as an array of strings). To avoid incorrect parsing when using thedefaults
command, it is recommended to enclose the regular expression in single quotes ('), and to prefix each string with a-string
argument. The regular expression is applied to the full path, and the contents of a file will be indexed 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 only index the contents of files whose extension is “.cp” or “.cpp” (case-insensitive), use one of these commands:
defaults write com.ctmdev.FoxTrotShared OnlyIndexContentsPathRegex -string '(?i)\.(cp|cpp)$'
defaults write com.ctmdev.FoxTrotShared OnlyIndexContentsPathRegex -array -string '(?i)\.cp$' -string '(?i)\.cpp$'
- The
OnlyIndexContentsPathRegex
preference applies to all your indices; to apply it to a single index, append the name of the index to the preference key (and enclose it in straight quotes), e.g.'OnlyIndexContentsPathRegex C++ files'
for an index named “C++ files” - See “Skipping some folders at indexing time” above about FoxTrot Personal.
- to only index the contents of files whose extension is “.cp” or “.cpp” (case-insensitive), use one of these commands:
Fine-tuning the garbage filter
- When a document contains large amounts of non-linguistic data (numbers, hexadecimal or encoded strings…), only the beginning of its content is indexed. You can change the settings of this garbage filter. By default, the filter is triggered when a document contains more than 10,000 new words (or alphanumeric strings) that do not appear in any other document, and only when these new words represent at least 15% of the words in the document.
defaults write com.ctmdev.FoxTrotShared GarbageFilterNewWordsPerFileMax -int
nbdefaults write com.ctmdev.FoxTrotShared GarbageFilterNewWordsPerFileMinPercentage -int
percent
Searching:
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 from macOS 10.15 to macOS 14.x, as it was actually much slower due to an Apple bug, fixed in macOS 15. To either force or disable multi-core preparation watever the version of macOS, 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
ndefaults 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
Miscellaneous:
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 Console.app (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 Console.app (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
totrue
in theConfig
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