From 74ba3885284b317ae599bb8d27055f9b674c46a2 Mon Sep 17 00:00:00 2001 From: Brendan Forster Date: Mon, 18 Jun 2018 06:54:30 -0300 Subject: [PATCH] first pass at some docs for this idea --- docs/metadata.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 docs/metadata.md diff --git a/docs/metadata.md b/docs/metadata.md new file mode 100644 index 00000000..1d199d95 --- /dev/null +++ b/docs/metadata.md @@ -0,0 +1,58 @@ +# Gitignore Metadata + +This document outlines the additional metadata that can be associated with a gitignore template, and how tools can consume this metadata. + +## Metadata Location + +To add additional metadata to a gitignore template, add a new file to the same directory, with the matching name but ending in `yml`. + +For example: + - for `C.gitignore` the associated metadata will be stored in `C.yml` + - for `Global/JetBrains.gitignore` the metadata file will be `Global/JetBrains.gitignore` + +## Supported Fields + +The structure of these files is still being settled upon, but for the moment these are some proposed entries. + +#### `aliases` + +Some templates can be used to represent a number of different situations, and rather than duplicating files on disk and needing to keep these in sync, we can store a list of these entries as metadata. + +For example, JetBrains has a unified gitignore template that can be applied to all of their IDEs. Previously these were stored as comments in the header: + +``` +# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and WebStorm +``` + +These values can be represented as metadata, so that tools consuming this repository can use these entries as matches if the user is searching for a specific product: + +```yaml +aliases: + - IntelliJ + - RubyMine + - PhpStorm + - AppCode + - PyCharm + - CLion + - Android Studio + - WebStorm + - Rider +``` + +#### `editors` + +There are a number of editors out there that support working with different languages. Rather than baking every editor's rules in every language that is supported, a list of additional templates that might be of interest + +```yaml +editors: + - Global/JetBrains.gitignore + - Global/VisualStudioCode.gitignore +``` + +#### `reference` + +Some ecosystems have up-to-date documentation about things that are necessary to exclude from version control. To associate this with a template, this could be stored as a key-value pair in metadata: + +```yaml +reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 +``` \ No newline at end of file