README
¶
outline
Reduce a source tree to a structural skeleton suitable for feeding to an LLM. Function and method bodies are dropped; signatures, types, comments and imports are kept. Unsupported file types pass through unchanged.
Pure Go, no CGo. Parsing is done by gotreesitter, file selection respects
.gitignore via git-pkgs/gitignore.
import "github.com/git-pkgs/outline"
r, err := outline.Pack(".", outline.Options{Compress: true})
if err != nil {
return err
}
r.Markdown(os.Stdout)
Or per file:
src, _ := os.ReadFile("main.go")
out, ok := outline.Outline(src, "main.go")
A Go file like
func SayHello(name string) {
fmt.Printf("Hello, %s!\n", name)
}
becomes
func SayHello(name string) {
⋮----
with the body elided and gaps marked by ⋮----.
API
Outline(src []byte, filename string) (string, bool) compresses one file. The
second return is false if the language is not supported.
Pack(root string, opts Options) (*Result, error) walks root, applies
.gitignore plus a built-in ignore list (vendored deps, build output,
lockfiles), skips binaries and oversized files, and outlines what it can.
Options lets you set size and file-count limits, extra ignore patterns,
concurrency, and whether to compress.
Result carries []File and a rendered Tree string. Result.Markdown(w)
and Result.XML(w) write the packed document.
Tree(paths []string) string renders a box-drawing directory tree from a flat
path list.
Languages
35 languages have body-stripping queries: Go, Ruby, Python, JavaScript,
TypeScript/TSX, Rust, Java, C, C++, C#, PHP, Kotlin, Swift, Scala, Dart,
Elixir, Erlang, Haskell, Clojure, Perl, Lua, R, Julia, OCaml, F#, Crystal, Nim,
Zig, D, Groovy, HCL/Terraform, Starlark/Bazel, CMake, Bash and Make.
gotreesitter ships ~200 grammars so adding a language means writing one .scm
query file.
Compared to repomix
This is roughly the --compress core of repomix reimplemented in Go. On the
same inputs it produces equivalent declaration coverage, preserves indentation
(repomix strips it), and avoids a few cases where repomix leaks function bodies
in Ruby and Python. It does not do token counting, secret scanning, or remote
cloning; those belong elsewhere in git-pkgs.
Performance
On an M1 Pro, outlining runs at ~2.5 MB/s per core and scales linearly across cores via a parser pool. Packing a ~40-file Go module takes about 45ms. The bottleneck is gotreesitter's full-parse path; our chunk extraction and rendering are negligible by comparison.
License
MIT
Documentation
¶
Index ¶
Constants ¶
const DefaultParseTimeout = time.Second
DefaultParseTimeout caps how long the parser will spend on a single file. Past this point the file is treated as unsupported and falls through as raw content. Pathological inputs (large table-driven test files, generated parser tables) can otherwise dominate runtime.
const Separator = "⋮----"
Variables ¶
This section is empty.
Functions ¶
func Outline ¶
Outline reduces source to a structural skeleton: declarations, signatures and comments are kept, function bodies are dropped. Returns the outline and true if the file's language is supported, otherwise "", false.
func SetParseTimeout ¶
SetParseTimeout overrides the per-file parse timeout. Must be called before the first Outline or Pack call; later calls are ignored once a language pool has been created. A zero duration disables the timeout.
Types ¶
type File ¶
type File struct {
Path string
Content string
Language string
Outlined bool
Size int64
Skipped string // reason content was omitted, e.g. "binary", "too-large"
}
File is one packed file.
type Options ¶
type Options struct {
// MaxFileSize is the per-file byte limit. Files larger than this are
// listed in the tree but their content is omitted. Zero means 1MB.
MaxFileSize int64
// MaxFiles caps the number of files read. Zero means 10000.
MaxFiles int
// Compress applies tree-sitter outlining to supported source files.
// When false, full file contents are kept.
Compress bool
// Ignore adds gitignore-syntax patterns on top of .gitignore and the
// built-in defaults.
Ignore []string
// Concurrency is the number of files processed in parallel.
// Zero means runtime.NumCPU().
Concurrency int
}
Options configures Pack.
type Result ¶
Result is the output of Pack.
func Pack ¶
Pack walks root, reads text files that survive gitignore and default filtering, optionally outlines them, and returns the collected result.
Source Files
Directories