Skip to content
Source plugin for pulling data into Gatsby from Git repositories (hosted anywhere)
JavaScript
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore Initial commit Oct 17, 2018
LICENSE Initial commit Oct 17, 2018
README.md Add some documentation Dec 5, 2018
gatsby-node.js Add sourceInstanceName to gitRepo nodes Dec 6, 2018
index.js
package-lock.json Remove now-redundant lodash.clonedeep dep Dec 5, 2018
package.json Bump version for publishing Mar 12, 2019

README.md

gatsby-source-git

Source plugin for pulling files into the Gatsby graph from abitrary Git repositories (hosted anywhere). This is useful if the markdown files you wish to render can't live within your gatsby codebase, or if need to aggregate content from disparate repositories.

It clones the repo(s) you configure (a shallow clone, into your cache folder if you're interested), and then sucks the files into the graph as File nodes, as if you'd configured gatsby-source-filesystem on that directory. As such, all the tranformer plugins that operate on files should work exactly as they do with gatsby-source-filesystem eg with gatsby-transformer-remark, gatsby-transformer-json etc.

The only difference is that the File nodes created by this plugin will also have a gitRemote field, which will provide you with various bits of Git related information. The fields on the gitRemote node are mostly provided by IonicaBazau/git-url-parse, with the addition of ref and weblink fields, which are the 2 main things you probably want if you're constructing "edit on github" style links.

Requirements

Requires git to be installed, and to be callable using the command git.

Ideally we'd use nodegit, but it doesn't support shallow clones (see libgit2/libgit2#3058) which would have a significant effect on build times if you wanted to read files from git repositories with large histories.

Only public repositories are supported right now. But a PR should be simple enough if you want that.

Install

Not published on npm yet, so for now:

npm install --save stevetweeddale/gatsby-source-git

How to use

// In your gatsby-config.js
module.exports = {
  plugins: [
    // You can have multiple instances of this plugin
    // to read source nodes from different repositories.
    {
      resolve: `gatsby-source-git`,
      options: {
        name: `repo-one`,
        remote: `https://bitbucket.org/stevetweeddale/markdown-test.git`,
        // Optionally supply a branch. If none supplied, you'll get the default branch.
        branch: `develop`,
        // Tailor which files get imported eg. import the docs folder from a codebase.
        patterns: `docs/**`
      }
    },
    {
      resolve: `gatsby-source-git`,
      options: {
        name: `repo-two`,
        remote: `https://bitbucket.org/stevetweeddale/markdown-test.git`,
        // Multiple patterns and negation supported. See https://github.com/mrmlnc/fast-glob
        patterns: [`*`, `!*.md`]
      }
    }
  ]
};

How to query

You can query file nodes exactly as you would node query for nodes created with gatsby-source-filesystem, eg:

{
  allFile {
    edges {
      node {
        extension
        dir
        modifiedTime
      }
    }
  }
}

Similarly, you can filter by the name you specified in the config by using sourceInstanceName:

{
  allFile(filter: { sourceInstanceName: { eq: "repo-one" } }) {
    edges {
      node {
        extension
        dir
        modifiedTime
      }
    }
  }
}

And access some information about the git repo:

{
  allFile {
    edges {
      node {
        gitRemote {
          webLink
          ref
        }
      }
    }
  }
}
You can’t perform that action at this time.