3. The .gitify File

To define what to export, to where and how, we're using a .gitify file formatted in YAML.

An example .gitify may look like this:

data_directory: _data/
data:
    contexts:
        class: modContext
        primary: key
    content:
        type: content
        exclude_keys:
            - editedby
            - editedon
    templates:
        class: modTemplate
        primary: templatename
        extension: .html
    categories:
        class: modCategory
        primary: category
        truncate_on_force:
            - modCategoryClosure
    template_variables:
        class: modTemplateVar
        primary: name
    chunks:
        class: modChunk
        primary: name
        extension: .html
    snippets:
        class: modSnippet
        primary: name
        extension: .php
    plugins:
        class: modPlugin
        primary: name
        extension: .php

The .gitify file structure is real simple. There are root nodes for data_directory (the relative path where to store the files) and data. data contains an array of directories to create. These directories then specify either a type that has special processing going on (i.e. content), or a class. The primary field determines the key to use in the name of the generated files. This defaults to id, but in many cases you may want to use the name as that is more human friendly.

By default files will be created with a .yaml extension, but if you want you can override that with a extension property. This can help with certain data and syntax highlighting in IDEs.

Third party packages (models)

When a certain class is not part of the core models, you can define a package as well. This will run $modx->addPackage before attempting to load the data. The path is determined by looking at a [package].core_path setting suffixed with model/, [[++core_path]]components/[package]/model/or a hardcoded package_path property. For example, you could use the following in your .gitify file to load ContentBlocks Layouts & Fields:

data:
    cb_fields:
        class: cbField
        primary: name
        package: contentblocks
    cb_layouts:
        class: cbLayout
        primary: name

As it'll load the package into memory, it's only required to add the package once. For clarify, it can't hurt to add it to each data entry that uses it.

Dealing with Closures

A Closure is a separate table in the database that a core or third party extra may use to keep information about a hierarchy in a convenient format. These are often automatically generated when creating a new object, which can result in a error messages and other issues when using Gitify build --force.

To solve this, a new truncate_on_force option was introduced in v0.6.0 that lets you define an array of class names that need their tables truncated on a force build. Truncating the closure table(s) before a forced build ensures that the model can properly create the rows in the closure table, without throwing errors.

Here are two examples of using truncate_on_force:

data:
    categories:
        class: modCategory
        primary: category
        truncate_on_force:
            - modCategoryClosure

    quip_comments:
        class: quipComment
        package: quip
        primary: [thread, id]
        truncate_on_force: 
            - quipCommentClosure

Composite Primary Keys

When an object doesn't have a single primary key, or you want to get fancy, it's possible to define a composite primary key, by setting the primary attribute to an array. For example, like this:

data:
    chunks:
        class: modChunk
        primary: [category, name]
        extension: .html

That would grab the category and the name as primary keys, and join them together with a dot in the file name. This is a pretty bad example, and you shouldn't really use it like this.

Install MODX Packages

Setup Package Providers and Install MODX Packages via the .gitify File.

data:
packages:
        modx.com:
            service_url: http://rest.modx.com/extras/
            packages:
                - Ace
                - Wayfinder
        modmore.com:
            service_url: https://rest.modmore.com/
            username: username
            api_key: .modmore.com.key
            packages:
                - clientConfig

When specifying an api_key on a provider, like in the example above, the value provided is the name of a file that contains the actual API Key. So the value of .modmore.com.key in the example above loads the file /path/to/your/base/directory/.modmore.com.key. This file needs to be kept out of the git repository using a .gitignore file, and you will also want to protect direct read access to it with your .htaccess file or keeping it out of the webroot.