gnaw

Learn Templating

Prerequisites

Ensure you have gnaw installed. If you haven't installed it yet, refer to the Installation Guide.

What are Handlebars Templates?

Handlebars is a popular templating engine that allows you to create dynamic templates using placeholders. In gnaw, Handlebars templates are used to format the generated prompts based on the codebase structure and user-defined variables.

How to use Handlebars Templates

You can use these templates by passing the -t or --template flag followed by a built-in template name or the path to a custom template file. For example:

sh 
gnaw path/to/codebase -t document-the-code
gnaw path/to/codebase -t templates/my-template.hbs

A built-in name is matched first; anything else is treated as a path to a custom .hbs file on disk.

Template Syntax

Handlebars templates use a simple syntax for placeholders and expressions. You will place variables in double curly braces {{variable_name}} to include them in the generated prompt. gnaw provides a set of default variables that you can use in your templates:

  • absolute_code_path: The absolute path to the codebase.
  • source_tree: The source tree of the codebase, which includes all files and directories.
  • files: A list of files in the codebase, including their paths and contents.
  • git_diff: The working-tree git diff, if --diff was passed.
  • git_diff_branch: The diff between two branches, if --git-diff-branch was passed.
  • git_log_branch: The commit log between two branches, if --git-log-branch was passed.
  • code: The code content of the file being processed.
  • path: The path of the file being processed.

You can also use Handlebars helpers to perform conditional logic, loops, and other operations within your templates. For example:

{{#if files}}
  {{#each files}}
    File:
    {{this.path}}
    Content:
    {{this.content}}
  {{/each}}
{{else}}
  No files found.
{{/if}}

Built-in Templates

gnaw comes with a set of built-in templates for common use cases. You can find them in the templates directory. Pass any of these names to -t / --template:

Model-specific layouts: claude-xml, chatgpt-markdown, gemini.

Code tasks: document-the-code, find-security-vulnerabilities, clean-up-code, fix-bugs, refactor, improve-performance, write-github-readme.

Git narratives: write-git-commit, write-git-changeset-commits, write-github-pull-request. These reason about a change, so they pair with the git flags — see Git diffs and logs.

CTF solvers: binary-exploitation-ctf-solver, cryptography-ctf-solver, reverse-engineering-ctf-solver, web-ctf-solver.

User Defined Variables

gnaw supports the use of user defined variables in the Handlebars templates. Any variables in the template that are not part of the default context (absolute_code_path, source_tree, files, and the per-file fields exposed inside {{#each files}}) will be treated as user defined variables.

During prompt generation, gnaw will prompt the user to enter values for these user defined variables. This allows for further customization of the generated prompts based on user input.

For example, if your template includes {{challenge_name}} and {{challenge_description}}, you will be prompted to enter values for these variables when running gnaw.