# Organizing snippets

## Table of Contents

- Basic structure
- Setting up `yas-snippet-dirs`
- The `.yas-parents` file
- TODO The `.yas-make-groups` file
- The `.yas-setup.el` file
- The `.yas-compiled-snippet.el` file
- The `.yas-skip` file

## Basic structure

Snippet collections can be stored in plain text files. They are arranged by sub-directories naming snippet tables. These mostly name Emacs major mode names.

    .
    |-- c-mode
    |   `-- printf
    |-- java-mode
    |   `-- println
    `-- text-mode
        |-- email
        `-- time

The collections are loaded into snippet tables which the triggering mechanism (see Expanding Snippets) looks up and (hopefully) causes the right snippet to be expanded for you.

## Setting up `yas-snippet-dirs`

The emacs variable `yas-snippet-dirs` tells YASnippet which collections to consider. It's used when you activate `yas-global-mode` or call `yas-reload-all` interactively.

The default considers:

- a personal collection that lives in `~/.emacs.d/snippets`
- the bundled collection, taken as a relative path to `yasnippet.el` location

When you come across other snippet collections, do the following to try them out:

    ;; Develop in ~/emacs.d/mysnippets, but also
    ;; try out snippets in ~/Downloads/interesting-snippets
    (setq yas-snippet-dirs '("~/emacs.d/mysnippets"
                               "~/Downloads/interesting-snippets"))

    ;; OR, keeping YASnippet defaults try out ~/Downloads/interesting-snippets
    (setq yas-snippet-dirs (append yas-snippet-dirs
                                   '("~/Downloads/interesting-snippets")))

Collections appearing earlier in the list override snippets with same names appearing in collections later in the list. `yas-new-snippet` always stores snippets in the first collection.

## The `.yas-parents` file

It's very useful to have certain modes share snippets between themselves. To do this, choose a mode subdirectory and place a `.yas-parents` containing a whitespace-separated list of other mode names. When you reload those modes become parents of the original mode.

    .
    |-- c-mode
    |   |-- .yas-parents    # contains "cc-mode text-mode"
    |   `-- printf
    |-- cc-mode
    |   |-- for
    |   `-- while
    |-- java-mode
    |   |-- .yas-parents    # contains "cc-mode text-mode"
    |   `-- println
    `-- text-mode
        |-- email
        `-- time

## TODO The `.yas-make-groups` file

If you place an empty plain text file `.yas-make-groups` inside one of the mode directories, the names of these sub-directories are considered groups of snippets and the menu is organized much more cleanly:

Another way to achieve this is to place a `# group:` directive inside the snippet definition. See Writing Snippets.

    $ tree ruby-mode/
    ruby-mode/
    |-- .yas-make-groups
    |-- collections
    |   |-- each
    |   `-- ...
    |-- control structure
    |   |-- forin
    |   `-- ...
    |-- definitions
    |   `-- ...
    `-- general
       `-- ...

Yet another way to create a nice snippet menu is to write into `.yas-make-groups` a menu definition. TODO

## The `.yas-setup.el` file

If there is file named `.yas-setup.el` in a mode's snippet subdirectory, it is loaded along with the snippets. Utility functions used by the snippets can be put here.

## The `.yas-compiled-snippet.el` file

You may compile a top-level snippet directory with the `yas-compile-directory` function, which will create a `.yas-compiled-snippets.el` file under each mode subdirectory, which contains definitions for all snippets in the subdirectory. Compilation helps improve loading time.

Alternatively, you may compile all directories in the list `yas-snippet-dirs` with the `yas-recompile-all` function.

## The `.yas-skip` file

A `.yas-skip` file in a mode's snippet subdirectory tells YASnippet not to load snippets from there.

Generated by Emacs 30.1 (Org mode 9.7.11) from 0.14.0 (2025-02-28 12:48:59)

Validate