https://github.com/urmzd/fsrc
Embed source files into any text file using comment markers — CLI, crate, and GitHub Action.
https://github.com/urmzd/fsrc
automation ci-cd cli code-embedding developer-tools documentation embed github-actions markdown rust showcase
Last synced: about 1 month ago
JSON representation
Embed source files into any text file using comment markers — CLI, crate, and GitHub Action.
- Host: GitHub
- URL: https://github.com/urmzd/fsrc
- Owner: urmzd
- License: apache-2.0
- Created: 2022-11-25T22:07:46.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-20T03:07:36.000Z (about 2 months ago)
- Last Synced: 2026-04-27T10:02:42.129Z (about 1 month ago)
- Topics: automation, ci-cd, cli, code-embedding, developer-tools, documentation, embed, github-actions, markdown, rust, showcase
- Language: Rust
- Homepage:
- Size: 471 KB
- Stars: 1
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
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:**
```markdown
```
**Rust / JS / Go / C:**
```rust
// fsrc src="path/to/utils.py"
// /fsrc
```
**Python / Shell / YAML:**
```python
# fsrc src="path/to/setup.sh"
# /fsrc
```
**CSS:**
```css
/* fsrc src="path/to/theme.css" */
/* /fsrc */
```
**SQL / Lua:**
```sql
-- 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:**
````markdown
```yaml
server:
host: localhost
port: 8080
```
````
- 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)
```sh
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:**
```sh
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](https://github.com/urmzd/fsrc/releases/latest) 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:
```bash
# 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
```yaml
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
```yaml
- 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:
```yaml
- 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:
```yaml
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](https://github.com/vercel-labs/skills) for use with Claude Code, Cursor, and other compatible agents.
Available as portable agent skills in [`skills/`](skills/).
Once installed, use `/fsrc` to embed source files into documents using comment markers.
## License
Apache-2.0