@jbrowse/cli 4.3.0 → 5.0.0-beta.1

package/dist/commands/set-default-session.js

@@ -1,7 +1,5 @@
-import { promises as fsPromises } from 'fs';
-import { parseArgs } from 'util';
-import parseJSON from 'json-parse-better-errors';
-import { printHelp, readJsonFile, resolveConfigPath, writeJsonFile, } from "../utils.js";
+import { parseArgs } from 'node:util';
+import { isRecord, printHelp, readConfigFile, readJsonFile, resolveConfigPath, writeJsonFile, } from '../utils.js';
 const description = 'Set a default session with views and tracks';
 const examples = [
     '# set default session for the config.json in your current directory',
@@ -10,20 +8,28 @@ const examples = [
     '# make session.json the defaultSession on the specified target config.json file',
     '$ jbrowse set-default-session --target /path/to/jb2/installation/config.json --session session.json',
     '',
-    '# print current default session',
-    '$ jbrowse set-default-session --currentSession # Prints out current default session',
+    '# override the name stored in the session file',
+    '$ jbrowse set-default-session --session session.json --name "My default view"',
+    '',
+    '# pipe a session in from another program',
+    `$ jq '.defaultSession' other/config.json | jbrowse set-default-session --session -`,
+    '',
+    '# print the current default session',
+    '$ jbrowse set-default-session --currentSession',
+    '',
+    '# remove the existing default session',
+    '$ jbrowse set-default-session --delete',
 ];
 const options = {
     session: {
         type: 'string',
         short: 's',
-        description: 'set path to a file containing session in json format (required, unless using delete/currentSession flags)',
+        description: 'set path to a file containing session in json format, or "-" to read it from stdin (required, unless using delete/currentSession flags)',
     },
     name: {
         type: 'string',
         short: 'n',
-        description: 'Give a name for the default session',
-        default: 'New Default Session',
+        description: 'Give a name for the default session (overrides any name in the session file; defaults to "New Default Session")',
     },
     currentSession: {
         type: 'boolean',
@@ -47,14 +53,14 @@ export async function run(args) {
         printHelp({
             description,
             examples,
-            usage: 'jbrowse add-track <track> [options]',
+            usage: 'jbrowse set-default-session [options]',
             options,
         });
         return;
     }
-    const { session, currentSession, delete: deleteDefaultSession } = runFlags;
+    const { session, name, currentSession, delete: deleteDefaultSession, } = runFlags;
     const target = await resolveConfigPath(runFlags.target, runFlags.out);
-    const configContents = await readJsonFile(target);
+    const configContents = await readConfigFile(target);
     if (deleteDefaultSession) {
         configContents.defaultSession = undefined;
         await writeJsonFile(target, configContents);
@@ -65,30 +71,28 @@ export async function run(args) {
     else if (!session) {
         throw new Error('Please provide a --session file');
     }
-    else if (session) {
+    else {
+        const fileSession = await readDefaultSessionFile(session);
         await writeJsonFile(target, {
             ...configContents,
-            defaultSession: await readDefaultSessionFile(session),
+            // precedence: explicit --name > the session file's own name > fallback
+            defaultSession: {
+                name: 'New Default Session',
+                ...fileSession,
+                ...(name !== undefined ? { name } : {}),
+            },
         });
     }
 }
 async function readDefaultSessionFile(defaultSessionFile) {
-    let defaultSessionJson;
-    try {
-        defaultSessionJson = await fsPromises.readFile(defaultSessionFile, {
-            encoding: 'utf8',
-        });
-    }
-    catch (error) {
-        throw new Error('Could not read the provided file');
-    }
-    try {
-        const session = parseJSON(defaultSessionJson);
-        // return top-level "session" if it exists, such as in files created by
-        // "File -> Export session"
-        return session.session || session;
-    }
-    catch (error) {
-        throw new Error('Could not parse the given default session file');
+    const contents = await readJsonFile(defaultSessionFile);
+    // unwrap the top-level "session" if it exists, such as in files created by
+    // "File -> Export session"
+    const session = contents.session ?? contents;
+    // spreading a string or an array here silently wrote a defaultSession of
+    // numeric keys, so say what is wrong with the file instead
+    if (!isRecord(session)) {
+        throw new Error(`${defaultSessionFile} does not contain a session object${contents.session === undefined ? '' : ' under its "session" key'}`);
     }
+    return session;
 }

package/dist/commands/shared/config-operations.js

@@ -1,14 +1,10 @@
-import { debug, writeJsonFile } from "../../utils.js";
-/**
- * Generic function to find and update or add an item to a config array
- * Returns the updated config and whether an item was overwritten
- */
-export function findAndUpdateOrAdd({ items, newItem, idField, getId, allowOverwrite, itemType, }) {
+import { debug, writeJsonFile } from '../../utils.js';
+export function findAndUpdateOrAdd({ items, newItem, idField, getId, force, itemType, }) {
     const newId = getId(newItem);
     const idx = items.findIndex(item => getId(item) === newId);
     if (idx !== -1) {
         debug(`Found existing ${itemType} ${newId} in configuration`);
-        if (allowOverwrite) {
+        if (force) {
             debug(`Overwriting ${itemType} ${newId} in configuration`);
             const updatedItems = [...items];
             updatedItems[idx] = newItem;
@@ -22,9 +18,6 @@ export function findAndUpdateOrAdd({ items, newItem, idField, getId, allowOverwr
         return { updatedItems: [...items, newItem], wasOverwritten: false };
     }
 }
-/**
- * Saves a config file and reports the result to the user
- */
 export async function saveConfigAndReport({ config, target, itemType, itemName, itemId, wasOverwritten, }) {
     debug(`Writing configuration to file ${target}`);
     await writeJsonFile(target, config);

package/dist/commands/shared/sort-utils.js

@@ -1,7 +1,11 @@
-import { spawn } from 'child_process';
-import tmp from 'tmp';
+import { spawn } from 'node:child_process';
+import { parseArgs } from 'node:util';
+import { fileSync } from 'tmp';
+import { printHelp } from '../../utils.js';
+import { describeExit, diedOfSigpipe, waitForProcessClose, } from '../process-utils.js';
+import { validateFileArgument, validateRequiredCommands } from './validators.js';
 export const BED_CONFIG = {
-    description: 'Helper utility to sort BED files for tabix. Moves all lines starting with # to the top of the file, and sort by refname and start position using unix utilities sort and grep',
+    description: 'Sort a BED file for tabix. It is `sort -k1,1 -k2,2n` with LC_ALL=C and a tab separator, plus every line starting with # kept at the top rather than sorted into the data. Takes a file, or the same data on stdin',
     examples: [
         '# sort bed and pipe to bgzip',
         '$ jbrowse sort-bed input.bed | bgzip > sorted.bed.gz',
@@ -13,7 +17,7 @@ export const BED_CONFIG = {
     fileType: 'bed',
 };
 export const GFF_CONFIG = {
-    description: 'Helper utility to sort GFF files for tabix. Moves all lines starting with # to the top of the file, and sort by refname and start position using unix utilities sort and grep',
+    description: 'Sort a GFF or GTF for tabix — the two share a refname/start column layout. It is `sort -k1,1 -k4,4n` with LC_ALL=C and a tab separator, plus every line starting with # kept at the top rather than sorted into the data. Takes a file, or the same data on stdin',
     examples: [
         '# sort gff and pipe to bgzip',
         '$ jbrowse sort-gff input.gff | bgzip > sorted.gff.gz',
@@ -21,6 +25,10 @@ export const GFF_CONFIG = {
         '',
         '# sort gff from stdin',
         '$ cat input.gff | jbrowse sort-gff | bgzip > sorted.gff.gz',
+        '',
+        '# also works on GTF',
+        '$ jbrowse sort-gff input.gtf | bgzip > sorted.gtf.gz',
+        '$ tabix -p gff sorted.gtf.gz',
     ],
     sortColumn: 4,
     fileType: 'gff',
@@ -31,20 +39,69 @@ function getMinimalEnvironment() {
         LC_ALL: 'C',
     };
 }
+// The file path is passed to the shell as the positional argument "$1" rather
+// than interpolated into the command string, so a path containing shell
+// metacharacters (`"`, `$(...)`, backticks) cannot break out and execute. Only
+// sortColumn, an integer from the BED/GFF configs, is interpolated.
+function sortPipeline(sortColumn) {
+    return `grep "^#" "$1"; grep -v "^#" "$1" | sort -t"\`printf '\\t'\`" -k1,1 -k${sortColumn},${sortColumn}n`;
+}
 function createSortCommandForStdin(sortColumn) {
-    const tmpFile = tmp.fileSync({ prefix: 'jbrowse-sort' }).name;
-    const sortCmd = `sort -t"\`printf '\\t'\`" -k1,1 -k${sortColumn},${sortColumn}n`;
-    return `cat > ${tmpFile} && (grep "^#" ${tmpFile}; grep -v "^#" ${tmpFile} | ${sortCmd}) && rm -f ${tmpFile}`;
+    // discardDescriptor: we only want the path — the shell below opens the file
+    // itself, so tmp's own handle would just be a descriptor left open for the
+    // life of the process
+    const tmpFile = fileSync({
+        prefix: 'jbrowse-sort',
+        discardDescriptor: true,
+    }).name;
+    // trap on EXIT removes the temp file whether or not the sort pipeline
+    // succeeds (a bare `&& rm` leaks the file when the pipeline fails)
+    return {
+        command: `trap 'rm -f "$1"' EXIT; cat > "$1" && (${sortPipeline(sortColumn)})`,
+        pathArg: tmpFile,
+    };
 }
 function createSortCommandForFile(file, sortColumn) {
-    return `(grep "^#" "${file}"; grep -v "^#" "${file}" | sort -t"\`printf '\\t'\`" -k1,1 -k${sortColumn},${sortColumn}n)`;
+    return { command: `(${sortPipeline(sortColumn)})`, pathArg: file };
 }
 export function spawnSortProcess(file, sortColumn) {
-    const command = file
+    const { command, pathArg } = file
         ? createSortCommandForFile(file, sortColumn)
         : createSortCommandForStdin(sortColumn);
-    return spawn('sh', ['-c', command], {
+    // 'sh' becomes $0, pathArg becomes $1 inside the command
+    return spawn('sh', ['-c', command, 'sh', pathArg], {
         env: getMinimalEnvironment(),
         stdio: 'inherit',
     });
 }
+export async function runSort(config, commandName, args) {
+    const options = { help: { type: 'boolean', short: 'h' } };
+    const { values: flags, positionals } = parseArgs({
+        args,
+        options,
+        allowPositionals: true,
+    });
+    if (flags.help) {
+        printHelp({
+            description: config.description,
+            examples: config.examples,
+            usage: `jbrowse ${commandName} [file] [options]`,
+            options,
+        });
+        return;
+    }
+    const file = positionals[0];
+    validateFileArgument(file, commandName, config.fileType);
+    validateRequiredCommands(['sh', 'sort', 'grep']);
+    const child = spawnSortProcess(file, config.sortColumn);
+    const exit = await waitForProcessClose(child);
+    // These commands exist to be piped (`jbrowse sort-bed in.bed | bgzip > …`), so
+    // a consumer that stops reading early — `| head`, `| grep -q` — must not be
+    // reported as a sort failure. It used to exit 1 with "exited with code 141".
+    if (diedOfSigpipe(exit)) {
+        return;
+    }
+    if (exit.code !== 0) {
+        throw new Error(`Sort process exited with ${describeExit(exit)}`);
+    }
+}

package/dist/commands/shared/validators.js

@@ -1,14 +1,49 @@
-import { sync as commandExistsSync } from 'command-exists';
+import { execFileSync } from 'node:child_process';
+import { accessSync, constants, statSync } from 'node:fs';
 export function validateFileArgument(file, commandName, fileType) {
-    if (!file && process.stdin.isTTY) {
+    if (file) {
+        // The sort pipeline's exit status is `sort`'s, which succeeds on empty
+        // input, so a missing/unreadable file would otherwise "succeed" with empty
+        // output. Fail loudly here instead.
+        if (!statSync(file, { throwIfNoEntry: false })?.isFile()) {
+            throw new Error(`Input file does not exist or is not a regular file: ${file}`);
+        }
+        try {
+            accessSync(file, constants.R_OK);
+        }
+        catch {
+            throw new Error(`Input file is not readable: ${file}`);
+        }
+    }
+    else if (process.stdin.isTTY) {
         throw new Error(`Missing required argument: file\n` +
             `Usage: jbrowse ${commandName} <file>\n` +
             `       OR pipe data via stdin: cat file.${fileType} | jbrowse ${commandName}`);
     }
 }
+// Replaces command-exists: is `command` runnable? On POSIX, `command -v` (a
+// shell builtin, so invoked via `sh`) resolves builtins, PATH entries, and
+// absolute paths; on Windows, `where` does the same. The name is passed as an
+// argv item, never interpolated into the shell, so it can't be injected.
+function commandExistsSync(command) {
+    try {
+        if (process.platform === 'win32') {
+            execFileSync('where', [command], { stdio: 'ignore' });
+        }
+        else {
+            execFileSync('sh', ['-c', 'command -v "$1"', 'sh', command], {
+                stdio: 'ignore',
+            });
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export function validateRequiredCommands(requiredCommands) {
     const missingCommands = requiredCommands.filter(cmd => !commandExistsSync(cmd));
     if (missingCommands.length > 0) {
-        throw new Error(`Unable to run command, requires unix type environment with: ${requiredCommands.join(', ')}`);
+        throw new Error(`Unable to run command, requires a unix type environment with the following available: ${requiredCommands.join(', ')}. Missing: ${missingCommands.join(', ')}`);
     }
 }

package/dist/commands/sort-bed.js

@@ -1,35 +1,4 @@
-import { parseArgs } from 'util';
-import { printHelp } from "../utils.js";
-import { waitForProcessClose } from "./process-utils.js";
-import { BED_CONFIG, spawnSortProcess } from "./shared/sort-utils.js";
-import { validateFileArgument, validateRequiredCommands, } from "./shared/validators.js";
+import { BED_CONFIG, runSort } from './shared/sort-utils.js';
 export async function run(args) {
-    const options = {
-        help: {
-            type: 'boolean',
-            short: 'h',
-        },
-    };
-    const { values: flags, positionals } = parseArgs({
-        args,
-        options,
-        allowPositionals: true,
-    });
-    if (flags.help) {
-        printHelp({
-            description: BED_CONFIG.description,
-            examples: BED_CONFIG.examples,
-            usage: 'jbrowse sort-bed [file] [options]',
-            options,
-        });
-        return;
-    }
-    const file = positionals[0];
-    validateFileArgument(file, 'sort-bed', 'bed');
-    validateRequiredCommands(['sh', 'sort', 'grep']);
-    const child = spawnSortProcess(file, BED_CONFIG.sortColumn);
-    const exitCode = await waitForProcessClose(child);
-    if (exitCode !== 0) {
-        throw new Error(`Sort process exited with code ${exitCode}`);
-    }
+    return runSort(BED_CONFIG, 'sort-bed', args);
 }

package/dist/commands/sort-gff.js

@@ -1,35 +1,4 @@
-import { parseArgs } from 'util';
-import { printHelp } from "../utils.js";
-import { waitForProcessClose } from "./process-utils.js";
-import { GFF_CONFIG, spawnSortProcess } from "./shared/sort-utils.js";
-import { validateFileArgument, validateRequiredCommands, } from "./shared/validators.js";
+import { GFF_CONFIG, runSort } from './shared/sort-utils.js';
 export async function run(args) {
-    const options = {
-        help: {
-            type: 'boolean',
-            short: 'h',
-        },
-    };
-    const { values: flags, positionals } = parseArgs({
-        args,
-        options,
-        allowPositionals: true,
-    });
-    if (flags.help) {
-        printHelp({
-            description: GFF_CONFIG.description,
-            examples: GFF_CONFIG.examples,
-            usage: 'jbrowse sort-gff [file] [options]',
-            options,
-        });
-        return;
-    }
-    const file = positionals[0];
-    validateFileArgument(file, 'sort-gff', 'gff');
-    validateRequiredCommands(['sh', 'sort', 'grep']);
-    const child = spawnSortProcess(file, GFF_CONFIG.sortColumn);
-    const exitCode = await waitForProcessClose(child);
-    if (exitCode !== 0) {
-        throw new Error(`Sort process exited with code ${exitCode}`);
-    }
+    return runSort(GFF_CONFIG, 'sort-gff', args);
 }

package/dist/commands/text-index/adapter-utils.js

@@ -1,38 +1,21 @@
-import { sanitizeNameForPath } from "./config-utils.js";
-export function getLoc(elt) {
-    return elt.locationType === 'LocalPathLocation' ? elt.localPath : elt.uri;
-}
+import { sanitizeForFilename, trixFileUris } from '@jbrowse/text-indexing-core';
 export function createTrixAdapter(name, assemblyNames, idSuffix = 'index') {
-    const safeName = sanitizeNameForPath(name);
+    const uris = trixFileUris(name);
     return {
         type: 'TrixTextSearchAdapter',
-        textSearchAdapterId: `${safeName}-${idSuffix}`,
+        textSearchAdapterId: `${sanitizeForFilename(name)}-${idSuffix}`,
         ixFilePath: {
-            uri: `trix/${safeName}.ix`,
+            uri: uris.ix,
             locationType: 'UriLocation',
         },
         ixxFilePath: {
-            uri: `trix/${safeName}.ixx`,
+            uri: uris.ixx,
             locationType: 'UriLocation',
         },
         metaFilePath: {
-            uri: `trix/${safeName}_meta.json`,
+            uri: uris.meta,
             locationType: 'UriLocation',
         },
         assemblyNames,
     };
 }
-const ADAPTER_LOCATION_KEYS = {
-    Gff3TabixAdapter: 'gffGzLocation',
-    Gff3Adapter: 'gffLocation',
-    VcfAdapter: 'vcfLocation',
-    VcfTabixAdapter: 'vcfGzLocation',
-};
-export function getAdapterLocation(adapter) {
-    const key = ADAPTER_LOCATION_KEYS[adapter?.type ?? ''];
-    return key
-        ? // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
-            (adapter?.[key] ??
-                adapter)
-        : undefined;
-}

package/dist/commands/text-index/aggregate.js

@@ -1,13 +1,15 @@
-import { createTrixAdapter } from "./adapter-utils.js";
-import { getAssemblyNames, getTrackConfigs, loadConfigForIndexing, parseCommaSeparatedString, prepareIndexDriverFlags, writeConf, } from "./config-utils.js";
-import { indexDriver } from "./indexing-utils.js";
-import { resolveConfigPath } from "../../utils.js";
+import { parseCommaSeparatedString, writeJsonFile } from '../../utils.js';
+import { createTrixAdapter } from './adapter-utils.js';
+import { formatDryRun, getAssemblyNames, getTrackConfigs, loadConfigForIndexing, prepareIndexDriverFlags, } from './config-utils.js';
+import { indexDriver } from './indexing-utils.js';
 export async function aggregateIndex(flags) {
-    const { out, target, tracks, excludeTracks, assemblies, attributes, quiet, force, exclude, dryrun, prefixSize, } = flags;
-    const { config, configPath, outLocation } = await loadConfigForIndexing(target, out, resolveConfigPath);
-    const aggregateTextSearchAdapters = config.aggregateTextSearchAdapters || [];
-    const asms = getAssemblyNames(config, assemblies);
-    for (const asm of asms) {
+    const { out, target, tracks, excludeTracks, assemblies, attributes, quiet, force, exclude, include, dryrun, prefixSize, } = flags;
+    const { config, configPath, outLocation } = await loadConfigForIndexing(target, out);
+    const existing = config.aggregateTextSearchAdapters ?? [];
+    // sequential, not Promise.all: each assembly's indexer owns the progress bar
+    // and streams whole files through ixIxx
+    const written = [];
+    for (const asm of getAssemblyNames(config, assemblies)) {
         const trackConfigs = getTrackConfigs(config, parseCommaSeparatedString(tracks), asm, parseCommaSeparatedString(excludeTracks));
         if (!trackConfigs.length) {
             console.log(`Indexing assembly ${asm}...(no tracks found)...`);
@@ -15,35 +17,39 @@ export async function aggregateIndex(flags) {
         }
         console.log(`Indexing assembly ${asm}...`);
         if (dryrun) {
-            console.log(trackConfigs.map(e => `${e.trackId}	${e.adapter?.type}`).join('\n'));
+            console.log(formatDryRun(trackConfigs));
+            continue;
         }
-        else {
-            const id = `${asm}-index`;
-            const idx = aggregateTextSearchAdapters.findIndex(x => x.textSearchAdapterId === id);
-            if (idx !== -1 && !force) {
-                console.log(`Note: ${asm} has already been indexed with this configuration, use --force to overwrite this assembly. Skipping for now`);
-                continue;
-            }
-            await indexDriver({
-                trackConfigs,
-                outLocation,
-                name: asm,
-                assemblyNames: [asm],
-                ...prepareIndexDriverFlags({ attributes, exclude, quiet, prefixSize }),
-            });
-            const trixConf = createTrixAdapter(asm, [asm]);
-            if (idx === -1) {
-                aggregateTextSearchAdapters.push(trixConf);
-            }
-            else {
-                aggregateTextSearchAdapters[idx] = trixConf;
-            }
+        const trixConf = createTrixAdapter(asm, [asm]);
+        if (!force &&
+            existing.some(x => x.textSearchAdapterId === trixConf.textSearchAdapterId)) {
+            console.log(`Note: ${asm} has already been indexed with this configuration, use --force to overwrite this assembly. Skipping for now`);
+            continue;
         }
+        await indexDriver({
+            trackConfigs,
+            outLocation,
+            name: asm,
+            assemblyNames: [asm],
+            ...prepareIndexDriverFlags({
+                attributes,
+                exclude,
+                include,
+                quiet,
+                prefixSize,
+            }),
+        });
+        written.push(trixConf);
     }
     if (!dryrun) {
-        writeConf({
+        await writeJsonFile(configPath, {
             ...config,
-            aggregateTextSearchAdapters,
-        }, configPath);
+            // upsert by adapter id: a Map keyed on it keeps the first occurrence's
+            // position while the last value wins, so re-indexing an assembly replaces
+            // its adapter in place and a new one lands at the end
+            aggregateTextSearchAdapters: [
+                ...new Map([...existing, ...written].map(a => [a.textSearchAdapterId, a])).values(),
+            ],
+        });
     }
 }

package/dist/commands/text-index/command.js

@@ -1,6 +1,7 @@
-import { parseArgs } from 'util';
-import { aggregateIndex, indexFileList, perTrackIndex } from "./index.js";
-import { printHelp } from "../../utils.js";
+import { parseArgs } from 'node:util';
+import { defaultAttributesToIndex, indexableAdapters, } from '@jbrowse/text-indexing-core';
+import { printHelp } from '../../utils.js';
+import { aggregateIndex, indexFileList, perTrackIndex } from './index.js';
 export async function run(args) {
     const options = {
         help: {
@@ -14,7 +15,7 @@ export async function run(args) {
         },
         excludeTracks: {
             type: 'string',
-            description: 'Specific tracks to exclude from indexing, formatted as comma separated trackIds',
+            description: 'Specific tracks to exclude from indexing, formatted as comma separated trackIds. To exclude a track permanently, set metadata.skipTextIndex on it in config.json instead (see Notes)',
         },
         target: {
             type: 'string',
@@ -24,7 +25,7 @@ export async function run(args) {
         attributes: {
             type: 'string',
             description: 'Comma separated list of attributes to index',
-            default: 'Name,ID',
+            default: defaultAttributesToIndex.join(','),
         },
         assemblies: {
             type: 'string',
@@ -49,9 +50,13 @@ export async function run(args) {
         },
         exclude: {
             type: 'string',
-            description: 'Adds gene type to list of excluded types',
+            description: 'Comma separated list of feature types to exclude from indexing',
             default: 'CDS,exon',
         },
+        include: {
+            type: 'string',
+            description: 'Comma separated list of feature types to index, dropping every other type. Unset by default, which indexes every type --exclude does not name. GFF3 only',
+        },
         prefixSize: {
             type: 'string',
             description: 'Specify the prefix size for the ixx index. We attempt to automatically calculate this, but you can manually specify this too. If many genes have similar gene IDs e.g. Z000000001, Z000000002 the prefix size should be larger so that they get split into different bins',
@@ -76,6 +81,28 @@ export async function run(args) {
         options,
     });
     const description = 'Make a text-indexing file for any given track(s).';
+    const notes = 'Individual tracks in config.json can be permanently excluded from ' +
+        'indexing by setting "metadata": { "skipTextIndex": true } on the track. ' +
+        'Such tracks are skipped even when indexing all tracks or a whole ' +
+        'assembly, so you do not have to pass --excludeTracks on every run.\n\n' +
+        // read off the table rather than restated, because the hand-written version
+        // of this sentence outlived GtfTabixAdapter's absence from it
+        `Only tracks with an indexable adapter type (${Object.keys(indexableAdapters).sort().join(', ')}) are indexed; ` +
+        'tracks with other adapter types are skipped automatically.\n\n' +
+        'GTF has no Name/ID attributes, so the default --attributes also match ' +
+        'their GTF spellings (gene_name, transcript_name, gene_id, transcript_id).' +
+        '\n\n' +
+        '--exclude names types not to index; --include names the only types to ' +
+        'index. Reach for --include when the file draws from a vocabulary you do ' +
+        'not control: an NCBI RefSeq GFF3 uses 115 feature types, 80 of them leaf ' +
+        'records with no name to search (a match is labelled with a bare UUID, a ' +
+        'cDNA_match with an MD5, every biological_region with the string ' +
+        '"biological region"), so a deny list leaks whichever type is added next ' +
+        'while the allow list — gene, pseudogene and the transcript types — does ' +
+        'not grow. Both may be given: --include admits, --exclude then narrows. ' +
+        'Either can also be set per track in config.json as ' +
+        'textSearching.indexingFeatureTypesToInclude / ' +
+        'indexingFeatureTypesToExclude, which takes precedence over the flag.';
     const examples = [
         "# indexes all tracks that it can find in the current directory's config.json",
         '$ jbrowse text-index',
@@ -84,7 +111,7 @@ export async function run(args) {
         '$ jbrowse text-index --tracks=track1,track2,track3',
         '',
         '# indexes all tracks except specific trackIds',
-        '$ jbrowse text-index --exclude-tracks=track1,track2,track3',
+        '$ jbrowse text-index --excludeTracks=track1,track2,track3',
         '',
         "# indexes all tracks in a directory's config.json or in a specific config file",
         '$ jbrowse text-index --out /path/to/jb2/',
@@ -99,6 +126,7 @@ export async function run(args) {
         printHelp({
             description,
             examples,
+            notes,
             usage: 'jbrowse text-index [options]',
             options,
         });