@cardstack/git

This is a Cardstack data source plugin for reading and writing to Git. Always have access to see how data has changed across time.

Features:

• Just like using git for code, your data is versioned. A deleted or changed record can be retrieved!
• Card data can be saved to either local or remote git repositories
• Data can be stored in either the same repository as the project code, or a separate repository
• Data for multiple projects can be saved to the same repository

Installing in a Cardstack project

To use a git as a data source, include @cardstack/git in the devDependencies of cardhost/package.json

yarn add --dev @cardstack/git
yarn install

See the "Troubleshooting" section of this README if you encounter any issues installing.

Configuration

Data plugins are configured in cardhost/data-sources. The only required configuration is to set either repo or remote.

Parameter	Type	Description
remote	object	Use a remote git repository, such as one hosted on Github. The object should contain url and privateKey with type string. Example: remote: { url: 'some-url', privateKey: process.env.GIT_PRIVATE_KEY}
repo	string	The path to a local git repository that already exists on disk, and has an initial commit
branchPrefix	string	optional - a prefix to prepend to the git branch when saving data. This is especially useful when you are storing data in the same repository as your project, or you have one repository that holds code for multiple projects. Example: if you set basePath: 'cs-', data will be stored at cs-master
basePath	string	optional - specify the directory within a repository where the data should be stored. Example: if you set basePath to my/base and you save an article Card, data will be stored at my/base/contents/articles/

You can set variables such as process.env.GIT_PRIVATE_KEY from the command line. For the example below, substitute your own path to the key:

GIT_PRIVATE_KEY="your private key here"

Example configuration

For example, the configuration below is set in cardhost/data-sources/default.js. This config creates a @cardstack/git data source named default and configures it as the Hub's default-data-source. Now, if a Card does not have its own data source defined, it will use git.

let sources = [
  {
    type: 'plugin-configs',
    id: '@cardstack/hub',
    attributes: {
      'plugin-config': {
        'application-card': { type: 'app-cards', id: 'cardhost' }
      }
    },
    relationships: {
      'default-data-source': {
        data: { type: 'data-sources', id: 'default' }
      }
    }
  },
  {
    type: 'data-sources',
    id: 'default',
    attributes: {
      'source-type': '@cardstack/git',
      params: {
        repo: '/path/to/some-git-repo'
      }
    }
  }
];

module.exports = sources;

Learn more

To learn more about how it can be used in your project, see the Cardstack Guides about git.

Troubleshooting

Windows installation - Building native nodegit dep

Windows users should install windows-build-tools, which are needed in order to build the nodegit dependency.

OSX installation - Building native nodegit dep

You need the latest Xcode and you need to manually tell it to get the latest CLI tools via

sudo xcode-select --install

Merely upgrading Xcode will still leave you broken and frustrated.

I cloned and built nodegit in its own repo, and then used yarn link. This seems to function as insurance against yarn deciding to rebuild it from scratch (which takes a long time).

Mac OS X Mojave users beware: nodegit does not appear to be compatible with the newer style OpenSSH keys that are generated by default from ssh-keygen. When generating ssh keys make sure to specify -m PEM in the ssh-keygen command in order to generate the older style PEM keypair. If you encounter the error:

Error: Failed to authenticate SSH session: Unable to extract public key from private key.

Then it is likely because you are generating the newer style OpenSSH keypair.

The older PEM style private keys (that are compatible with nodegit) are identifable by having a private key preamble that begins with:

-----BEGIN RSA PRIVATE KEY-----

More information is detailed here: https://github.com/nodegit/nodegit/issues/1606.

In order to use the private key as an env var in TravisCI you will need to replace the newlines in the private key. This issue describes this more in detail: https://github.com/travis-ci/travis-ci/issues/7715#issuecomment-362536708. You can use the following perl script to convert newlines into \n from the private key file and write to stdout:

$ perl -p -e 's/\n/\\n/' ~/.ssh/my-private-key_id_rsa

Then in Travis you can specify the env var in the following in manner within the Travis env var text field for the newlines to be converted correctly. Note that the " and ' characters are very critical:

"$(echo -e '-----BEGIN RSA PRIVATE KEY-----\nMKOQ1zYTmd\nzkRpTFq4xu\n-----END RSA PRIVATE KEY-----\n')"