SourceConcat.jl

Concatenate your project’s source files into a single, navigable Markdown document — complete with syntax highlighting, table of contents, and clipboard export.

---

✨ Overview

SourceConcat.jl walks your source tree, collects files that match glob patterns, and concatenates them into a single Markdown file.

It’s handy for:

• Building context packs for AI tools or documentation
• Creating portable snapshots of a codebase
• Rapid code reviews and shareable archives

---

⚙️ Installation

using Pkg
Pkg.add(url="https://github.com/josePereiro/SourceConcat.jl.git")

---

🚀 Quick start

1. Put a configuration file at your project root named SourceConcat.json (or SrcConcat.json).
2. From Julia, call:

using SourceConcat
concat(log = true)

Output modes

Mode	Description
"file"	Write concatenated Markdown to output.path.
"clipboard-text"	Copy concatenated text to the clipboard (up to an internal size limit).
"clipboard-file"	Write the file to disk and copy a file reference to the clipboard.
"terminal"	Print the concatenated Markdown to stdout.

---

🧩 Example configuration

{
  "root.paths": [ "." ],
  "output.path": "~/Documents/context.md",
  "output.mode": "clipboard-file",
  "include.files": [
    "*.jl",
    "*.md",
    "*Project.toml",
    "*SourceConcat.json"
  ],
  "exclude.files": [
    "_DEPRECATED/**",
    ".git/**",
    "dev/**"
  ],
  "use.gitignore": true
}

Main keys

Key	Type	Description
root.paths	Vector{String}	Root directories to walk
output.path	String	Destination Markdown path
output.mode	String	One of: "file", "clipboard-text", "clipboard-file", "terminal"
include.files	Vector{String}	Glob patterns to include
exclude.files	Vector{String}	Glob patterns to exclude
use.gitignore	Bool	When true, patterns in .gitignore are respected for exclusion

Config filenames: either SourceConcat.json or SrcConcat.json is recognized.

---

🧠 Example output

<!-- Generated by SourceConcat.jl at 2025-11-08 10:15:44 -->

***
## TABLE OF CONTENTS
1. [Content of 'Project.toml'](#sc-1)
2. [Content of 'src/SourceConcat.jl'](#sc-2)
...

---

🖥️ Shell alias / function (Bash)

Add one of these to your ~/.bashrc or ~/.zshrc.

Minimal alias (runs in current directory)

alias srcconcat='julia -e "using SourceConcat; SourceConcat.concat()"'

Usage:

# From a repo that has SourceConcat.json
srcconcat

Small helper function

srcconcat() {
    # global
    julia -e 'using SourceConcat; SourceConcat.concat()'
}

Examples:

# Use the active environment
srcconcat

The function simply invokes SourceConcat.concat() in the current working directory, where the tool will look for SourceConcat.json.

---

📋 Clipboard file support

When output.mode is "clipboard-file", the Markdown is written to disk and a file reference is copied to your clipboard, so you can paste directly into a AI chat as an attachment.

Platform	Backend	Details
macOS	osascript	AppleScript: set the clipboard to POSIX file "..."
Windows	PowerShell	Uses .NET System.Windows.Forms.Clipboard via STA thread
Linux	wl-copy / xclip	GNOME-compatible x-special/gnome-copied-files, falls back to text/uri-list

Implementation: src/utils.clipboard.file.jl

---

🧪 Development

using Pkg
Pkg.test("SourceConcat")

Planned:

• Nested .gitignore parsing and !pattern support
• Parallel reading for large trees
• Command-line interface
• HTML / JSON export options

---

🧱 Project structure

SourceConcat.jl/
├── Project.toml
├── SourceConcat.json          # example configuration
├── data/
│   └── SourceConfig.example.json
├── src/
│   ├── SourceConcat.jl
│   ├── base.*.jl
│   ├── utils.clipboard.file.jl
│   ├── utils.gitignore.jl
│   └── utils.config.example.jl
├── test/
│   └── runtests.jl
└── notes/

---

📄 License

MIT © 2025 José Pereiro