{"id":13725741,"url":"https://github.com/stevetweeddale/gatsby-source-git","last_synced_at":"2025-05-07T20:33:40.513Z","repository":{"id":34293969,"uuid":"153429328","full_name":"stevetweeddale/gatsby-source-git","owner":"stevetweeddale","description":"Source plugin for pulling data into Gatsby from Git repositories (hosted anywhere)","archived":false,"fork":false,"pushed_at":"2023-10-26T13:33:41.000Z","size":125,"stargazers_count":68,"open_issues_count":14,"forks_count":29,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-11-13T19:07:34.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stevetweeddale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-10-17T09:17:23.000Z","updated_at":"2024-08-14T15:07:04.000Z","dependencies_parsed_at":"2023-10-16T10:51:59.337Z","dependency_job_id":"bc2f0911-4800-4b9c-8d5b-a3a147b53d69","html_url":"https://github.com/stevetweeddale/gatsby-source-git","commit_stats":{"total_commits":39,"total_committers":6,"mean_commits":6.5,"dds":0.3846153846153846,"last_synced_commit":"a7fee1aa2c139033e5214a2622f9a701064b36b1"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevetweeddale%2Fgatsby-source-git","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevetweeddale%2Fgatsby-source-git/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevetweeddale%2Fgatsby-source-git/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stevetweeddale%2Fgatsby-source-git/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stevetweeddale","download_url":"https://codeload.github.com/stevetweeddale/gatsby-source-git/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224645568,"owners_count":17346185,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T01:02:33.203Z","updated_at":"2024-11-14T15:32:00.945Z","avatar_url":"https://github.com/stevetweeddale.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# gatsby-source-git\n\nSource 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.\n\nIt clones the repo(s) you configure (a shallow clone, into your cache folder if\nyou're interested), and then sucks the files into the graph as `File` nodes, as\nif you'd configured\n[`gatsby-source-filesystem`](https://www.gatsbyjs.org/packages/gatsby-source-filesystem/)\non that directory. As such, all the tranformer plugins that operate on files\nshould work exactly as they do with `gatsby-source-filesystem` eg with\n`gatsby-transformer-remark`, `gatsby-transformer-json` etc.\n\nThe only difference is that the `File` nodes created by this plugin will\nalso have a `gitRemote` field, which will provide you with various bits of\nGit related information. The fields on the `gitRemote` node are\nmostly provided by\n[IonicaBazau/git-url-parse](https://github.com/IonicaBizau/git-url-parse), with\nthe addition of `ref` and `weblink` fields, which are\nthe 2 main things you probably want if you're constructing \"edit on github\"\nstyle links.\n\nN.B. Although with respect to sourcing this works as a drop-in replacement for `gatsby-source-filesystem`, there are a number of helpers included in that module (`createFilePath`, `createRemoteFileNode`, `createFileNodeFromBuffer`) that are not duplicated here – but you can still import and use them from there as needed.\n\n## Requirements\n\nRequires [git](http://git-scm.com/downloads) to be installed, and to be callable using the command `git`.\n\nIdeally we'd use [nodegit](https://github.com/nodegit/nodegit), but it doesn't support shallow clones (see [libgit2/libgit2#3058](https://github.com/libgit2/libgit2/issues/3058)) which would have a significant effect on build times if you wanted to read files from git repositories with large histories.\n\n## Install\n\n`npm install --save gatsby-source-git`\n\n## Configuration\n\n### Plugin options\n\n- `name`: A machine name label for each plugin instance.\n- `remote`: The url to clone from.\n- `branch` (optional): The branch or tag to use. If none supplied, we try to use the\n  'default' branch.\n- `patterns` (optional): Passed to\n  [fast-glob](https://github.com/mrmlnc/fast-glob) to determine which files get\n  sucked into the graph.\n- `local` (optional): Specify the local path for the cloned repo. If omitted,\n  it will default to a directory within the local Gatsby cache. Note that using\n  a location outside the cache will prevent you changing the branch via\n  gatsby-config.js. You will need to synchronise the branch of the local\n  checkout yourself. However if clones are painful and slow for you, then using\n  a custom location will prevent your local repo getting trashed when Gatsby\n  clears the cache, which should help.\n\n### Example gatsby-config.js\n\n```javascript\nmodule.exports = {\n  plugins: [\n    // You can have multiple instances of this plugin to read source files from\n    // different repositories or locations within a repository.\n    {\n      resolve: `gatsby-source-git`,\n      options: {\n        name: `repo-one`,\n        remote: `https://bitbucket.org/stevetweeddale/markdown-test.git`,\n        branch: `develop`,\n        // Only import the docs folder from a codebase.\n        patterns: `docs/**`,\n        // The \"--depth\" command line argument of Git. Set to 0 if you need accurate file modified time.\n        fetchDepth: 1\n      }\n    },\n    {\n      resolve: `gatsby-source-git`,\n      options: {\n        name: `repo-two`,\n        remote: `https://bitbucket.org/stevetweeddale/markdown-test.git`,\n        // Specify the local checkout location, to avoid it being trashed on\n        // cache clears.\n        local: '/explicit/path/to/repo-two',\n        // Multiple patterns and negation supported. See https://github.com/mrmlnc/fast-glob\n        patterns: [`*`, `!*.md`]\n      }\n    }\n  ]\n};\n```\n\nThis will result in `File` nodes being put in your data graph, it's then up to you to do whatever it is you want to do with that data.\n\n### Private repositories\n\nMost git hosting providers support authentication via URL, either in the form of username and password or more commonly access tokens. So to use a private github repository as an example, you would firstly [generate a personal access token](https://help.github.com/en/github/authenticating-to-github/creating-a-personal-access-token-for-the-command-line). Now you don't want that in your repo, so instead you'd [set an OS environment variable](https://www.gatsbyjs.org/docs/environment-variables/#server-side-nodejs) and then read that environment variable into your plugin config something like:\n\n```javascript\n{\n  resolve: `gatsby-source-git`,\n  options: {\n    name: `my-repo`,\n    remote: `https://myuser:${process.env.GITHUB_TOKEN}@github.com/myuser/my-repo`,\n  },\n}\n```\n\n## How to query\n\nYou can query file nodes exactly as you would node query for nodes created with\n[`gatsby-source-filesystem`](https://www.gatsbyjs.org/packages/gatsby-source-filesystem/),\neg:\n\n```graphql\n{\n  allFile {\n    edges {\n      node {\n        extension\n        dir\n        modifiedTime\n        message\n        authorName\n      }\n    }\n  }\n}\n```\n\nSimilarly, you can filter by the `name` you specified in the config by using\n`sourceInstanceName`:\n\n```graphql\n{\n  allFile(filter: { sourceInstanceName: { eq: \"repo-one\" } }) {\n    edges {\n      node {\n        extension\n        dir\n        modifiedTime\n        message\n        authorName\n      }\n    }\n  }\n}\n```\n\nAnd access some information about the git repo:\n\n```graphql\n{\n  allFile {\n    edges {\n      node {\n        gitRemote {\n          webLink\n          ref\n        }\n      }\n    }\n  }\n}\n```\n\n## Creating pages\n\nIf you want to programatically create pages on your site from the files in your git repo, you should be able to follow the standard examples, such as [part 7 of the Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-seven/) or [the standard docs page](https://www.gatsbyjs.org/docs/creating-and-modifying-pages/#creating-pages-in-gatsby-nodejs).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevetweeddale%2Fgatsby-source-git","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstevetweeddale%2Fgatsby-source-git","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstevetweeddale%2Fgatsby-source-git/lists"}