Schema Reference

This page documents the configuration schemas for common-repo.

v1 Schema (Legacy)

The original v1 schema from commonrepo. This has been superseded by the v2 schema with operators.

######################
# CommonRepo v1 schema
#
# This is the original schema definition for the v1 of commonrepo. This has been
# superceded by the v2 common-repo.
#
# This schema has the problem where the operations like "include", "rename" and
# "exclude" are applied in a fixed order, and only once, which is inflexible and
# actually more difficult to implement than operators. It also makes it more
# difficult to implement new operators in the form of plugins.
#
# This v1 schema is from the codebase at https://github.com/shakefu/commonrepo.

#########
# Upstreams
#
# Upstream repositories define which of their files should be imported into the
# child repository.
#
# This should be defined in the `.commonrepo.yml` file.
#
# The bare minimum configuration is a single `include: ["**/*"]` entry.

# include opts-in files and folders based on globbing patterns
include:
  # Everything
  - "**/*"
  # Every hidden file
  - .*
  # Every hidden directory
  - .*/**/*
  # Everything in the files/ directory
  - files/**/*
  # Individual file
  - .gitignore

# after the full list of included files is built, the exclusion filters are
# applied to remove any unwanted files from the working list
exclude:
  # Template related workflows
  - .github/workflows/template_*
  # Markdown files
  - "**/*.md"

# before renames are applied, files that are templates store the vars: context
template:
  - "templates/**"

# after the filtered list is created, destination file names are generated by
# passing the working list through the rename transforms, in order
rename:
  # Rename a path
  - "badname/(.*)": "goodname/$1"
  # Strip one directory from the path
  - "^files/(.*)": "$1"
  # Strip multiple directories from the path
  - "some/parent/dir/(.*)": "$1"
  # Recompose directories
  - "parent/([^/]+)/dir/(.*)": "$1/$2"
  # Add a prefix to the path
  - "(.*\\.md)": "docs/$1"
  # Move templates to repo root
  - "templates/(.*)": "$1"

# Install specs use SemVer constraints
install:
  # List of maps, where the key name matches the tool filename/path, the version
  # describes the desired version.
  - golang: 1.17.x
  - jq: ^1

# Optional override for path if you don't want to use the default
install-from: ./.commonrepo/install/

# Optional override for preferred install manager order
install-with: [apt-get, brew, platform]

---

###########
# Consumers
#
# Consumer repositories can define which upstream repos they want to consume from, as
# well as apply additional filters to the ones defined in the upstream repos.

# define a list of upstream repositories, which mimic the consumer repos keys
upstream:
  - url: https://github.com/shakefu/commonrepo
    ref: v1.1.0
    overwrite: false  # TBD if this should be implemented
    include: [.*]
    exclude: [.gitignore]
    rename: [{".*\\.md": "docs/$1"}]

# Template context for all upstreams...
template-vars:
  project: myprojectname

v2 Schema (Current)

The v2 schema uses operators for flexible, composable configuration. All operators are documented in the Configuration Reference.

Available operators: repo, include, exclude, rename, template, template-vars, tools, self, yaml, json, toml, ini, markdown.