.\" Generated by scdoc
.\" Complete documentation for this program is not available as a GNU info page
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.nh
.ad l
.\" Begin generated content:
.TH "TEXTCON" "1" "2026\-07\-10"
.PP
.SH NAME
.PP
textcon \- stream files and template references into one output
.PP
.SH SYNOPSIS
.PP
\fBtextcon\fR [options] \fIINPUT\fR.\&.\&.\&
.PP
\fBtextcon\fR \fB\-\-template\fR \fITEMPLATE\fR [options]
.PP
.SH DESCRIPTION
.PP
\fBtextcon\fR is a payload\-streaming context composer.\& Operand mode writes selected files in argument order.\& Template mode copies literal template bytes and substitutes explicit file or directory references as they are encountered.\&
.PP
Results are written only to standard output.\& Successful execution writes no status messages.\& A failure after earlier output leaves that prefix visible; callers must check the exit status.\&
.PP
.SH MODES
.PP
Operand mode accepts files, directories, and one \fB\-\fR stdin operand.\& A second \fB\-\fR is a usage error.\& Directories use the shared selection policy described below.\&
.PP
Template mode requires \fB\-\-template\fR.\& The value \fB\-\fR reads template bytes from stdin.\& The template source and direct operands are explicit caller authority and are not constrained by \fB\-\-sandbox\fR.\&
.PP
Supplying neither operands nor \fB\-\-template\fR is a usage error.\&
.PP
.SH RENDERING
.PP
\fB\-\-render markdown\fR is the default.\& Every direct input file and every descendant of a direct directory is emitted as:
.PP
.nf
.RS 4
# `encoded/logical/path`
unwrapped body
.fi
.RE
.PP
No code fence is synthesized.\& Source Markdown, raw HTML, remote images, or comment lines can therefore affect a Markdown preview.\& Treat generated bundles as untrusted Markdown and use a sanitizing viewer when needed.\&
.PP
Path labels use a lossless single\-line encoding.\& A labelled record is terminated with the minimum LF bytes needed for one blank line.\& Body bytes and existing line endings are otherwise preserved.\&
.PP
For paths ending in \fB.\&md\fR or \fB.\&markdown\fR (ASCII case\-insensitive), effective Markdown rendering shifts top\-level ATX H1 through H5 by one level.\& H6, Setext headings, indented code, fenced code, line endings, NUL, invalid UTF\-8, and all other bytes remain unchanged.\& The transformation is lexical, streaming, per\-source, and applied once.\&
.PP
\fB\-\-render raw\fR concatenates exact bytes without labels, separators, or Markdown adaptation.\&
.PP
.SH TEMPLATE REFERENCES
.PP
References have these forms:
.PP
.nf
.RS 4
{{ @path }}
{{ @path | markdown }}
{{ @path | raw }}
.fi
.RE
.PP
In inherited Markdown mode, a bare file reference emits an unlabelled adaptive body.\& A bare directory concatenates adaptive descendant bodies in selector order without separators.\& In inherited raw mode, both are byte\-exact.\&
.PP
For a file, \fB| markdown\fR re\-enables extension\-based Markdown adaptation but does not add a label.\& For a directory it emits an H1\-labelled record per descendant.\& \fB| raw\fR always disables labels, adaptation, and separators.\&
.PP
Processor names are lowercase and case\-sensitive.\& At least one ASCII whitespace byte must precede the processor pipe, so \fIa|b\fR remains a path.\& Use \fB\e|\fR and \fB\e}\fR for literal delimiter bytes in a path.\& Leading and trailing syntax whitespace is not part of the path.\& Paths must be nonempty UTF\-8 without NUL.\&
.PP
\fB\e{{\fR emits a literal \fB{{\fR.\& Odd and even runs of preceding backslashes are handled predictably.\& Unrelated brace constructs remain literal, while malformed, oversized, or unterminated reference\-like constructs fail with their original byte offset.\& A reference candidate is limited to 256 KiB.\&
.PP
Included bytes are never reparsed.\& Expansion is one\-pass and cannot recurse or cycle through placeholder text contained in a referenced file.\&
.PP
.SH PATH RESOLUTION AND SANDBOX
.PP
Relative references resolve beneath \fB\-\-base\-dir\fR, defaulting to the current directory.\& Without \fB\-\-sandbox\fR, absolute paths and \fB.\&.\&\fR use normal operating\-system semantics.\& On Unix, \fI{{ @/etc/fstab }}\fR therefore addresses \fI/etc/fstab\fR.\& Positional operands always resolve normally from the process working directory and are never retargeted by \fB\-\-base\-dir\fR.\&
.PP
\fB\-\-sandbox\fR opens the base directory as a filesystem capability and confines reference targets, descendant traversal, and ignore\-file reads beneath it.\& Absolute references are accepted only when they map beneath that root.\& Escaping \fB.\&.\&\fR components and symlinks that resolve outside the root fail; explicitly referenced symlinks that resolve inside the root may succeed.\& Discovered symlinks are skipped.\& The template source and direct operands remain outside this policy.\&
.PP
Sandboxing constrains namespace access; it does not create a filesystem snapshot, prevent concurrent mutation, or limit output size.\&
.PP
.SH DIRECTORY SELECTION
.PP
Top\-level operands/references retain their order and duplicates.\& Each directory is traversed depth\-first with siblings sorted by native path order.\& The default depth is unlimited; the requested directory is depth zero, so \fB\-\-max\-depth 0\fR selects no descendants and \fB\-\-max\-depth 1\fR selects immediate files.\&
.PP
Dot\-prefixed descendants are hidden unless \fB\-\-hidden\fR is supplied.\& Discovered symlinks, reparse points, and special files are skipped.\& Explicitly named regular files and symlinks bypass hidden, gitignore, and exclusion filtering.\&
.PP
\fB.\&gitignore\fR files are applied from the selection\-policy root through nested selected directories unless \fB\-\-no\-gitignore\fR is supplied.\& Global Git excludes, \fI.\&git/info/exclude\fR, and \fI.\&ignore\fR are not consulted.\&
.PP
Each \fB\-\-exclude\fR value is a gitignore\-style rule.\& Rules are evaluated in command\-line order after \fB.\&gitignore\fR; later matches win and a leading \fB!\&\fR re\-includes.\& A descendant cannot be reached through a pruned parent unless the parent is also re\-included.\& Hidden and symlink policies cannot be overridden by negation.\&
.PP
Traversal, metadata, ignore parsing, selected\-file read, and output errors are fatal.\& Already\-written output remains visible.\&
.PP
Source and template payload memory is independent of payload size.\& Deterministic sorting retains one directory'\&s entries at a time, and active ignore rules remain resident during their subtree traversal, so total memory also depends on maximum directory width and ignore\-rule size.\&
.PP
.SH OPTIONS
.PP
\fB\-t, \-\-template\fR \fIFILE\fR
.RS 4
Expand a template file.\& Use \fB\-\fR for standard input.\& Conflicts with operands.\&
.PP
.RE
\fB\-\-render\fR \fImarkdown|raw\fR
.RS 4
Select the inherited renderer.\& The default is \fBmarkdown\fR.\&
.PP
.RE
\fB\-b, \-\-base\-dir\fR \fIDIR\fR
.RS 4
Resolve relative template references beneath \fIDIR\fR.\& Valid only in template mode.\&
.PP
.RE
\fB\-\-sandbox\fR
.RS 4
Confine template references beneath the base directory.\& Valid only in template mode.\&
.PP
.RE
\fB\-d, \-\-max\-depth\fR \fIN\fR
.RS 4
Limit descendant depth for both directory forms.\&
.PP
.RE
\fB\-x, \-\-exclude\fR \fIPATTERN\fR
.RS 4
Append an ordered gitignore\-style selection rule.\& May be repeated.\&
.PP
.RE
\fB\-\-no\-gitignore\fR
.RS 4
Disable \fB.\&gitignore\fR processing.\&
.PP
.RE
\fB\-\-hidden\fR
.RS 4
Include dot\-prefixed descendants.\&
.PP
.RE
\fB\-h, \-\-help\fR
.RS 4
Show command help.\&
.PP
.RE
\fB\-V, \-\-version\fR
.RS 4
Show the textcon version.\&
.PP
.RE
.SH STANDARD INPUT AND OUTPUT
.PP
Use positional \fB\-\fR for direct stdin or \fB\-\-template \-\fR for template stdin.\& Standard output contains result bytes only.\& Shell redirection replaces an output\-file option.\&
.PP
When output is redirected to a file inside a selected directory, textcon identifies and skips that file so recursive discovery cannot ingest its own growing output.\& Explicitly naming the same file as stdout is an error.\&
.PP
A closed downstream pipe is quiet successful termination.\& Other write failures are fatal.\&
.PP
.SH EXIT STATUS
.PP
\fB0\fR
.RS 4
Success, including downstream BrokenPipe.\&
.PP
.RE
\fB1\fR
.RS 4
Template, filesystem, sandbox, input, rendering, or output failure.\&
.PP
.RE
\fB2\fR
.RS 4
Invalid command usage or invalid option value.\&
.PP
.RE
.SH ENVIRONMENT
.PP
No environment variable changes path resolution or selection semantics.\&
.PP
.SH EXAMPLES
.PP
Bundle shell\-expanded sources with path labels:
.PP
.nf
.RS 4
textcon src/*\&.rs > CODE\&.md
.fi
.RE
.PP
Concatenate exact bytes:
.PP
.nf
.RS 4
textcon \-\-render raw part1 part2 > combined
.fi
.RE
.PP
Expand a template from stdin with ambient absolute references:
.PP
.nf
.RS 4
printf \&'Host mounts:n{{ @/etc/fstab }}n\&' | textcon \-\-template \-
.fi
.RE
.PP
Expand a directory as labelled Markdown while confining references:
.PP
.nf
.RS 4
textcon \-\-template context\&.md \-\-base\-dir \&./project \-\-sandbox
.fi
.RE
.PP
Re\-include a file beneath an excluded directory by re\-including its parent first:
.PP
.nf
.RS 4
textcon \&. \-x generated/ \-x \&'!generated/\&' \-x \&'generated/*\&' \-x \&'!generated/keep\&.rs\&'
.fi
.RE
.PP
.SH SEE ALSO
.PP
\fBgitignore\fR(5), \fBpandoc\fR(1), \fBsh\fR(1)