fsrc

Embed source files into any text file using comment markers.

Download · Report Bug · GitHub Action

Showcase

Before	After

Syntax

Place opening and closing markers in your file using whatever comment style is appropriate:

Markdown / HTML:

<!-- fsrc src="path/to/config.yml" -->
<!-- /fsrc -->

Rust / JS / Go / C:

// fsrc src="path/to/utils.py"
// /fsrc

Python / Shell / YAML:

# fsrc src="path/to/setup.sh"
# /fsrc

CSS:

/* fsrc src="path/to/theme.css" */
/* /fsrc */

SQL / Lua:

-- fsrc src="path/to/schema.sql"
-- /fsrc

When the tool runs, the content between the markers is replaced with the referenced file’s contents.

Raw vs Fenced Insertion

By default, content is inserted raw (no wrapping). This works for any file type.

To wrap content in markdown code fences, use the fence attribute:

Attribute	Behavior
(none)	Raw insertion
`fence`	Code fence with auto-detected language
`fence="auto"`	Code fence with auto-detected language
`fence="python"`	Code fence with explicit language tag

Example with fencing:

<!-- fsrc src="path/to/config.yml" fence="auto" -->
```yaml
server:
  host: localhost
  port: 8080
```
<!-- /fsrc -->

Paths are relative to the host file’s directory.
The code fence language is inferred from the file extension when using fence or fence="auto".
Re-running is idempotent — existing content between markers is replaced.

Features

Any File Type: Embed into markdown, YAML, Python, Rust, or any file with comments.
Raw or Fenced: Insert raw content by default, or wrap in code fences with fence.
Custom Commit Options: Personalize commit messages, author details, and push behavior.
Dry-Run Mode: Test embedding without creating commits.
Seamless Integration: Drop into any GitHub Actions workflow.

Installation

Script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/urmzd/fsrc/main/install.sh | sh

Installs the latest release to $HOME/.local/bin and adds it to your shell’s PATH.

Options (environment variables):

Variable	Description	Default
`FSRC_VERSION`	Version to install (e.g. `v3.1.1`)	latest
`FSRC_INSTALL_DIR`	Installation directory	`$HOME/.local/bin`

Example — pin a version:

FSRC_VERSION=v3.1.1 curl -fsSL https://raw.githubusercontent.com/urmzd/fsrc/main/install.sh | sh

Manual

Download a pre-built binary for your platform from the releases page and place it somewhere on your PATH.

Windows — the script installer is not supported; use the manual download above.

Local Usage

The fsrc binary can also be used directly:

# Process files in place
fsrc run README.md docs/*.md

# Check if files are up-to-date (CI mode)
fsrc run --verify README.md

# Preview changes without writing
fsrc run --dry-run README.md

Inputs

Name	Description	Required	Default
`files`	Space-separated list of files to process.	No	`README.md`
`commit-message`	Commit message for the embedded changes.	No	`chore: embed source files`
`commit-name`	Git committer name.	No	`github-actions[bot]`
`commit-email`	Git committer email.	No	`github-actions[bot]@users.noreply.github.com`
`commit-push`	Whether to push after committing.	No	`true`
`commit-dry`	Skip the commit (dry-run mode).	No	`false`
`github-token`	GitHub token for downloading the binary.	No	`${{ github.token }}`

Usage

Basic

name: "Example"

on: [push]

jobs:
  embed:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: "Checkout repo"
        uses: actions/checkout@v4
      - name: "Embed code into files"
        uses: urmzd/fsrc@v4
        with:
          files: "README.md"

Multiple Files

- uses: urmzd/fsrc@v4
  with:
    files: "README.md docs/API.md docs/GUIDE.md"

Dry Run (No Commit)

Useful for CI validation — embed the files and check for drift without committing:

- uses: urmzd/fsrc@v4
  with:
    commit-dry: "true"
    commit-push: "false"

Troubleshooting

Action fails with “nothing to commit” This means no changes were needed. Ensure your files contain valid fsrc markers with src="..." and corresponding /fsrc closing markers.

Permission denied on push The action needs contents: write permission. Add this to your job:

permissions:
  contents: write

Files not being embedded Verify the file paths in files are relative to the repository root and that the referenced source files exist.

Agent Skill

This project ships an Agent Skill for use with Claude Code, Cursor, and other compatible agents.

Available as portable agent skills in skills/.

Once installed, use /fsrc to embed source files into documents using comment markers.

License

Apache-2.0