template-sync

Keep repository in sync with its template.

Generates pull requests to bring a repository back in sync with its template.

So by making changes to the template and applying template-sync the target project will be updated accoring to the template.

Works with github and bitbucket.

This is the engine for cli operation please see template-tools/template-sync-cli

Merges contents from template branch into destination branch handling some special cases for:

• Licenses - rewriting license years
• line set files like .npmignore and .gitignore - by merging both sets together
• package.json - merge (.*)[Dd]ependencies, engines and scripts
• rollup.conf.*js - copy / rewrite + detect dev dependencies
• *.yaml - merge
• .travis.yml - merge with hints
• *.toml - merge
• *.ini - merge
• *.json - merge
• README.md - merge badges

Some templates

• arlac77/template-cli-app rollup ava travis
• arlac77/template-esm-only ava travis
• arlac77/template-svelte-component svelte rollup testcafe travis
• arlac77/template-svelte-app svelte rollup pkgbuild travis
• arlac77/template-kronos-component template-esm-only with node 14
• arlac77/template-kronos-app node 14 + systemd

API

Table of Contents

• Context
  • Parameters
  • Properties
  • targetBranch
  • initialize
  • execute
  • commits
  • executeBranch
• pullRequestBranch
• sortedKeys
• exportsConditionOrder
• Package
  • properties
    • Parameters
• Merger
  • properties
    • Parameters
  • commits
    • Parameters
• Merger
  • Properties
  • properties
    • Parameters
  • commits
    • Parameters
• Readme
• MergeLineSet
• ReplaceIfEmpty
• Replace
• INI
• Skip
• Delete
• EntryMerger
  • Properties
• Template
  • Parameters
  • Properties
  • shortKey
  • entryMerger
    • Parameters
  • mergerFor
    • Parameters
  • _templateFrom
    • Parameters
  • updateUsedBy
    • Parameters
  • templateFor
    • Parameters
• normalizeTemplateSources
  • Parameters
• jspath
  • Parameters
• actions2message
  • Parameters
• actions2messages
  • Parameters

Context

Extends LogLevelMixin(class _Context {})

Context prepared to execute one branch.

Parameters

• provider Object
• targetBranch (Branch | string)
• options Object (optional, default {})

Properties

• ctx Object
• files Map<string, Object>

targetBranch

Type: (Branch | String)

initialize

Returns Promise<(Context | undefined)>

execute

Generate Pull Requests.

Returns AsyncIterable<PullRequest>

commits

Generate all commits from the template entry merges.

Returns AsyncIterable<Commit>

executeBranch

Generate Pull Requests.

Returns AsyncIterable<PullRequest> the actual PRs

pullRequestBranch

Type: String

sortedKeys

order in which json keys are written

exportsConditionOrder

• See: {https://nodejs.org/dist/latest/docs/api/packages.html#exports}

Order in which exports are searched

Package

Extends Merger

Merger for package.json

properties

Deliver some key properties.

• name
• version
• description
• main

Parameters

• entry ContentEntry

Returns Promise<Object>

Merger

Mergable content

properties

Deliver some key properties.

Parameters

• entry ContentEntry

Returns Promise<Object> extracted properties

commits

Generate commits as result of merging two entries.

Parameters

• context
• destinationEntry
• sourceEntry
• options

Returns AsyncIterable<Commit>

Merger

Type: Object

Properties

• type string
• pattern string
• factory Class
• options Object

properties

Deliver some key properties.

Parameters

• entry ContentEntry

Returns Promise<Object> extracted properties

commits

Generate commits as result of merging two entries.

Parameters

• context
• destinationEntry
• sourceEntry
• options

Returns AsyncIterable<Commit>

Readme

Extends Merger

Injects badges into README.md.

MergeLineSet

Extends Merger

ReplaceIfEmpty

Extends Merger

Overwrites none existing entries from template.

Replace

Extends Merger

Always overwrite entry from template

INI

Extends Merger

Merge ini entries

Skip

Extends Merger

Does not generate destination entry

Delete

Extends Merger

Delete entry.

EntryMerger

Type: Object

Properties

• name string
• factory Class
• options Object

Template

Extends LogLevelMixin(class {})

Parameters

• context Conext
• sources Array<string>
• options Object (optional, default {})

Properties

• context Conext
• sources Set<string>
• toBeRemovedSources Set<string>
• mergers Array<Merger>
• branches Set<Branch> all used branches direct and inherited
• keyBranches Set<Branch> branches used to define the template

shortKey

Used to identify generated branch.

Returns string short template key

entryMerger

Find a suitable merger for each entry

Parameters

• entries Iterator<ContentEntry>

Returns Iterator<[ContentEntry, Merger]>

mergerFor

Find a suitable merger

Parameters

• name string of the entry

Returns Merger

_templateFrom

Load all templates and collects the entries.

Parameters

• sources string branch names
• inheritencePath Array<Branch> who was requesting us (optional, default [])

Returns Object package as merged from sources

updateUsedBy

Updates usedBy section of the template branch.

Parameters

• targetBranch Branch template to be updated
• templateSources Array<string> original branch identifiers (even with deletion hints)
• options Object as passed to commitIntoPullRequest

Returns AsyncIterator<PullRequest>

templateFor

Load a template.

Parameters

• context Context
• sources Array<string>
• options Object

normalizeTemplateSources

Remove duplicate sources. Sources staring with '-' will be removed

Parameters

• sources Array<string>
• remove Array<string> (optional, default [])

Returns Array<string> normalized sources

jspath

Parameters

• object
• path
• cb

actions2message

Parameters

• actions
• prefix string
• name string

Returns any actions as one string lines ordered by scope

actions2messages

Parameters

• actions
• prefix string
• name string

install

With npm do:

npm install -g @template-tools/sync-cli

license

BSD-2-Clause