PkgTemplates User Guide

Template(; kwargs...)

A configuration used to generate packages.

Keyword Arguments

User Options

• user::AbstractString="gwr-de": GitHub (or other code hosting service) username. The default value comes from the global Git config (github.user). If no value is obtained, many plugins that use this value will not work.
• authors::Union{AbstractString, Vector{<:AbstractString}}="Guido Wolf Reichert <gwr@bsl-support.de> and contributors": Package authors. Like user, it takes its default value from the global Git config (user.name and user.email).

Package Options

• dir::AbstractString="~/.julia/dev": Directory to place packages in.
• host::AbstractString="github.com": URL to the code hosting service where packages will reside.
• julia::VersionNumber=v"1.10.10": Minimum allowed Julia version.

Template Plugins

• plugins::Vector{<:Plugin}=Plugin[]: A list of Plugins used by the template. The default plugins are ProjectFile, SrcDir, Tests, Readme, License, Git, Dependabot, TagBot and GitHubActions. To disable a default plugin, pass in the negated type: !PluginType. To override a default plugin instead of disabling it, pass in your own instance.

Interactive Mode

• interactive::Bool=false: In addition to specifying the template options with keywords, you can also build up a template by following a set of prompts. To create a template interactively, set this keyword to true. See also the similar generate function.

To create a package from a Template, use the following syntax:

julia> t = Template();

julia> t("PkgName")

generate([pkg::AbstractString]) -> Template

Shortcut for Template(; interactive=true)(pkg). If no package name is supplied, you will be prompted for one.

ProjectFile(; version=v"1.0.0-DEV")

Creates a Project.toml.

Keyword Arguments

• version::VersionNumber: The initial version of created packages.

SrcDir(; file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/src/module.jlt")

Creates a module entrypoint.

Keyword Arguments

• file::AbstractString: Template file for src/<module>.jl.

Tests(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/test/runtests.jlt",
    project=false,
    aqua=false,
    aqua_kwargs=NamedTuple(),
    jet=false,
)

Sets up testing for packages.

Keyword Arguments

• file::AbstractString: Template file for runtests.jl.
• project::Bool: Whether or not to create a new project for tests (test/Project.toml). See the Pkg docs for more details.
• aqua::Bool: Controls whether or not to add quality tests with Aqua.jl.
• aqua_kwargs::NamedTuple: Which keyword arguments to supply to Aqua tests (many people use ambiguities=false for example)
• jet::Bool: Controls whether or not to add a linting test with JET.jl (works best on type-stable code)

Readme(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/README.md",
    destination="README.md",
    inline_badges=false,
)

Creates a README file that contains badges for other included plugins.

Keyword Arguments

• file::AbstractString: Template file for the README.
• destination::AbstractString: File destination, relative to the repository root. For example, values of "README" or "README.rst" might be desired.
• inline_badges::Bool: Whether or not to put the badges on the same line as the package name.
• badge_order::Vector{typeof(Plugin)}: Plugins in the order their badges should appear.
• badge_off::Vector{typeof(Plugin)}: Plugins which should not have their badges added.

License(; name="MIT", path=nothing, destination="LICENSE")

Creates a license file.

Keyword Arguments

• name::AbstractString: Name of a license supported by PkgTemplates. Available licenses can be seen here.
• path::Union{AbstractString, Nothing}: Path to a custom license file. This keyword takes priority over name.
• destination::AbstractString: File destination, relative to the repository root. For example, "LICENSE.md" might be desired.

Git(;
    ignore=String[],
    name=nothing,
    email=nothing,
    branch=LibGit2.getconfig("init.defaultBranch", "main")
    ssh=false,
    jl=true,
    manifest=false,
    gpgsign=false,
)

Creates a Git repository and a .gitignore file.

Keyword Arguments

• ignore::Vector{<:AbstractString}: Patterns to add to the .gitignore. See also: gitignore.
• name::AbstractString: Your real name, if you have not set user.name with Git.
• email::AbstractString: Your email address, if you have not set user.email with Git.
• branch::AbstractString: The desired name of the repository's default branch.
• ssh::Bool: Whether or not to use SSH for the remote. If left unset, HTTPS is used.
• jl::Bool: Whether or not to add a .jl suffix to the remote URL.
• manifest::Bool: Whether or not to commit Manifest.toml.
• gpgsign::Bool: Whether or not to sign commits with your GPG key. This option requires that the Git CLI is installed, and for you to have a GPG key associated with your committer identity.

GitHubActions(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/github/workflows/CI.yml",
    destination="CI.yml",
    linux=true,
    osx=false,
    windows=false,
    x64=true,
    x86=false,
    coverage=true,
    extra_versions=["1.10", "1.12", "pre"],
)

Integrates your packages with GitHub Actions.

Keyword Arguments

• file::AbstractString: Template file for the workflow file.
• destination::AbstractString: Destination of the workflow file, relative to .github/workflows.
• linux::Bool: Whether or not to run builds on Linux.
• osx::Bool: Whether or not to run builds on OSX (MacOS).
• windows::Bool: Whether or not to run builds on Windows.
• x64::Bool: Whether or not to run builds on 64-bit architecture.
• x86::Bool: Whether or not to run builds on 32-bit architecture.
• coverage::Bool: Whether or not to publish code coverage. Another code coverage plugin such as Codecov must also be included.
• extra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.

Dependabot(; file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/github/dependabot.yml")

Sets up Dependabot to create PRs whenever GitHub Actions or Julia package dependencies can be updated. Monitors the root /, /docs, and /test directories for Julia dependencies.

As of December 2025, Dependabot supports Julia and is the recommended approach for keeping package dependencies up to date. This replaces the functionality previously provided by CompatHelper.

Keyword Arguments

• file::AbstractString: Template file for dependabot.yml.

TagBot(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/github/workflows/TagBot.yml",
    destination="TagBot.yml",
    trigger="JuliaTagBot",
    token=Secret("GITHUB_TOKEN"),
    ssh=Secret("DOCUMENTER_KEY"),
    ssh_password=nothing,
    changelog=nothing,
    changelog_ignore=nothing,
    gpg=nothing,
    gpg_password=nothing,
    registry=nothing,
    branches=nothing,
    dispatch=nothing,
    dispatch_delay=nothing,
)

Adds GitHub release support via TagBot.

Keyword Arguments

• file::AbstractString: Template file for the workflow file.
• destination::AbstractString: Destination of the workflow file, relative to .github/workflows.
• trigger::AbstractString: Username of the trigger user for custom registries.
• token::Secret: Name of the token secret to use.
• ssh::Secret: Name of the SSH private key secret to use.
• ssh_password::Secret: Name of the SSH key password secret to use.
• changelog::AbstractString: Custom changelog template.
• changelog_ignore::Vector{<:AbstractString}: Issue/pull request labels to ignore in the changelog.
• gpg::Secret: Name of the GPG private key secret to use.
• gpg_password::Secret: Name of the GPG private key password secret to use.
• registry::AbstractString: Custom registry, in the format owner/repo.
• branches::Bool: Whether or not to enable the branches option.
• dispatch::Bool: Whether or not to enable the dispatch option.
• dispatch_delay::Int: Number of minutes to delay for dispatch events.

Secret(name::AbstractString)

Represents a GitHub repository secret. When converted to a string, yields ${{ secrets.<name> }}.

AppVeyor(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/appveyor.yml",
    x86=false,
    coverage=true,
    extra_versions=["1.10", "1.12", "nightly"],
)

Integrates your packages with AppVeyor via AppVeyor.jl.

Keyword Arguments

• file::AbstractString: Template file for .appveyor.yml.
• x86::Bool: Whether or not to run builds on 32-bit systems, in addition to the default 64-bit builds.
• coverage::Bool: Whether or not to publish code coverage. Codecov must also be included.
• extra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.

CirrusCI(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/cirrus.yml",
    image="freebsd-12-0-release-amd64",
    coverage=true,
    extra_versions=["1.10", "1.12", "nightly"],
)

Integrates your packages with Cirrus CI via CirrusCI.jl.

Keyword Arguments

• file::AbstractString: Template file for .cirrus.yml.
• image::AbstractString: The FreeBSD image to be used.
• coverage::Bool: Whether or not to publish code coverage. Codecov must also be included.
• extra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.

DroneCI(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/drone.star",
    amd64=true,
    arm=false,
    arm64=false,
    extra_versions=["1.10", "1.12"],
)

Integrates your packages with Drone CI.

Keyword Arguments

• file::AbstractString: Template file for .drone.star.
• destination::AbstractString: File destination, relative to the repository root. For example, you might want to generate a .drone.yml instead of the default Starlark file.
• amd64::Bool: Whether or not to run builds on AMD64.
• arm::Bool: Whether or not to run builds on ARM (32-bit).
• arm64::Bool: Whether or not to run builds on ARM64.
• extra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.

GitLabCI(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/gitlab-ci.yml",
    coverage=true,
    extra_versions=["1.10", "1.12"],
)

Integrates your packages with GitLab CI.

Keyword Arguments

• file::AbstractString: Template file for .gitlab-ci.yml.
• coverage::Bool: Whether or not to compute code coverage.
• extra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.

GitLab Pages

Documentation can be generated by including a Documenter{GitLabCI} plugin. See Documenter for more information.

TravisCI(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/travis.yml",
    linux=true,
    osx=false,
    windows=false,
    x64=true,
    x86=false,
    arm64=false,
    coverage=true,
    extra_versions=["1.10", "1.12", "nightly"],
)

Integrates your packages with Travis CI.

Keyword Arguments

• file::AbstractString: Template file for .travis.yml.
• linux::Bool: Whether or not to run builds on Linux.
• osx::Bool: Whether or not to run builds on OSX (MacOS).
• windows::Bool: Whether or not to run builds on Windows.
• x64::Bool: Whether or not to run builds on 64-bit architecture.
• x86::Bool: Whether or not to run builds on 32-bit architecture.
• arm64::Bool: Whether or not to run builds on the ARM64 architecture.
• coverage::Bool: Whether or not to publish code coverage. Another code coverage plugin such as Codecov must also be included.
• extra_versions::Vector: Extra Julia versions to test, as strings or VersionNumbers.

Codecov(; file=nothing)

Sets up code coverage submission from CI to Codecov.

Keyword Arguments

• file::Union{AbstractString, Nothing}: Template file for .codecov.yml, or nothing to create no file.

Coveralls(; file=nothing)

Sets up code coverage submission from CI to Coveralls.

Keyword Arguments

• file::Union{AbstractString, Nothing}: Template file for .coveralls.yml, or nothing to create no file.

Documenter{T}(;
    make_jl="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/docs/make.jlt",
    index_md="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/docs/src/index.md",
    assets=String[],
    logo=Logo(),
    canonical_url=make_canonical(T),
    devbranch=nothing,
    edit_link=:devbranch,
    makedocs_kwargs=Dict{Symbol,Any}(),
)

Sets up documentation generation via Documenter.jl. Documentation deployment depends on T, where T is some supported CI plugin, or Nothing to only support local documentation builds.

using DocumenterTools; DocumenterTools.genkeys(user="MyUser", repo="MyPackage.jl")

Supported Type Parameters

• GitHubActions: Deploys documentation to GitHub Pages with the help of GitHubActions.
• TravisCI: Deploys documentation to GitHub Pages with the help of TravisCI.
• GitLabCI: Deploys documentation to GitLab Pages with the help of GitLabCI.
• NoDeploy (default): Does not set up documentation deployment.

Keyword Arguments

• make_jl::AbstractString: Template file for make.jl.
• index_md::AbstractString: Template file for index.md.
• assets::Vector{<:AbstractString}: Extra assets for the generated site.
• logo::Logo: A Logo containing documentation logo information.
• canonical_url::Union{Function, Nothing}: A function to generate the site's canonical URL. The default value will compute GitHub Pages and GitLab Pages URLs for TravisCI and GitLabCI, respectively. If set to nothing, no canonical URL is set.
• edit_link::Union{AbstractString, Symbol, Nothing}: Branch, tag or commit that the "Edit on…" link will point to. Defaults to the branch identified by devbranch. If edit_link=:commit, then the link will point to the latest commit when docs are built. If edit_link=nothing, then the "Edit on…" link will be hidden altogether.
• devbranch::Union{AbstractString, Nothing}: Branch that will trigger docs deployment. If nothing, then the default branch according to the Template will be used.
• makedocs_kwargs::Dict{Symbol,Any}: Extra keyword arguments to be inserted into makedocs.

Logo(; light=nothing, dark=nothing)

Logo information for documentation.

Keyword Arguments

• light::AbstractString: Path to a logo file for the light (default) theme.
• dark::AbstractString: Path to a logo file for the dark theme.

BlueStyleBadge()

Adds a BlueStyle badge to the Readme file.

ColPracBadge()

Adds a ColPrac badge to the Readme file.

PkgEvalBadge()

Adds a PkgEval badge to the Readme file.

Develop()

Adds generated packages to the current environment by deving them. See the Pkg documentation here for more details.

Citation(; file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/CITATION.bib", readme=false)

Creates a CITATION.bib file for citing package repositories.

Keyword Arguments

• file::AbstractString: Template file for CITATION.bib.
• readme::Bool: Whether or not to include a section about citing in the README.

RegisterAction(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/github/workflows/Register.yml",
    destination="Register.yml",
    prompt="Version to register or component to bump",
)

Add a GitHub Actions workflow for registering a package with the General registry via workflow dispatch. See here for more information.

Keyword Arguments

• file::AbstractString: Template file for the workflow file.
• destination::AbstractString: Destination of the workflow file, relative to .github/workflows.
• prompt::AbstractString: Prompt for workflow dispatch.

Formatter(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/.JuliaFormatter.toml",
    style="nostyle"
)

Create a .JuliaFormatter.toml file, used by JuliaFormatter.jl and the Julia VSCode extension to configure automatic code formatting.

This file can be entirely customized by the user, see the JuliaFormatter.jl docs.

Keyword Arguments

• file::String: Template file for .JuliaFormatter.toml.
• style::String: Style name, defaults to "nostyle" for an empty style but can also be one of ("sciml", "blue", "yas") for a fully preconfigured style.

CodeOwners <: Plugin
CodeOwners(; owners)

A plugin which created GitLab/GitHub compatible CODEOWNERS files. owners should be a vector of patterns mapped to a vector of owner names. For example: owners=["*"=>["@invenia"], "README.md"=>["@documentation","@oxinabox]] assigns general ownership over all files to the invenia group, but assigns ownership of the readme to the documentation group and to the user oxinabox.

By default, it creates an empty CODEOWNERS file.

PkgBenchmark(; file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/benchmark/benchmarks.jlt")

Sets up a PkgBenchmark.jl benchmark suite.

To ensure benchmark reproducibility, you will need to manually create an environment in the benchmark subfolder (for which the Manifest.toml is committed to version control). In this environment, you should at the very least:

• pkg> add BenchmarkTools
• pkg> dev your new package.

Keyword Arguments

• file::AbstractString: Template file for benchmarks.jl.

CompatHelper(;
    file="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/github/workflows/CompatHelper.yml",
    destination="CompatHelper.yml",
    cron="0 0 * * *",
)

Integrates your packages with CompatHelper via GitHub Actions.

Keyword Arguments

• file::AbstractString: Template file for the workflow file.
• destination::AbstractString: Destination of the workflow file, relative to .github/workflows.
• cron::AbstractString: Cron expression for the schedule interval.

Reuse(;
    license=nothing,
    artifact_license=nothing,
    docs_license=nothing,
    docs_assets_license=nothing,
    license_ref_dir=nothing,
    template="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/reuse/REUSE.toml.mustache",
    enable_reuse_lint=true,
    readme_license_section=false,
    license_section_template="~/Developer/JuliaLang/Packages/PkgTemplates.jl/templates/reuse/README_license_section.md.mustache",
    root_license=true,
    license_approval="code",
)

Set up a REUSE layout by generating REUSE.toml, copying the license and exception texts required by the configured SPDX license expressions into LICENSES/, and adding SPDX headers to generated source files.

SPDX-listed license and exception texts are taken exclusively from PkgTemplates’ bundled SPDX snapshot. Custom LicenseRef-... licenses are resolved from license_ref_dir. Only license texts required by the configured license expressions are written to LICENSES/.

Keyword Arguments

• license::Union{AbstractString, Nothing}: Primary SPDX license expression for the project code. If nothing, fall back to "MIT".
• artifact_license::Union{AbstractString, Nothing}: SPDX license expression for project artifacts and tooling files covered by REUSE.toml. Defaults to license.
• docs_license::Union{AbstractString, Nothing}: SPDX license expression for documentation text. Defaults to license.
• docs_assets_license::Union{AbstractString, Nothing}: SPDX license expression for documentation assets. Defaults to docs_license.
• license_ref_dir::Union{AbstractString, Nothing}: Optional directory containing user-supplied license texts for LicenseRef-... identifiers. For LicenseRef-X, Reuse prefers LicenseRef-X.txt.mustache, rendered to LICENSES/LicenseRef-X.txt, and otherwise copies LicenseRef-X.txt verbatim.
• template::AbstractString: Template file for REUSE.toml.
• enable_reuse_lint::Bool: Whether to add reuse lint to generated GitHub Actions workflows when the GitHubActions plugin is present.
• readme_license_section::Bool: Whether to append a ## Licensing section to the README file generated by the Readme plugin. If the Readme plugin is disabled or its destination file does not exist, no section is appended.
• license_section_template::String: Template file for the optional README licensing section.
• root_license::Bool: Whether to generate a conventional root LICENSE file. If all effective license domains, after applying defaults, resolve to the same single plain license without WITH exceptions, that license text is copied from LICENSES/ to root LICENSE. Otherwise, root LICENSE is generated as a short pointer to the REUSE layout. Defaults to true.
• license_approval::String: Controls optional checks against license approval metadata. The values "code", "strict", and "none" may be given. Defaults to "code".

SPDX License Expressions

• Use SPDX license identifiers and expressions such as MIT, Apache-2.0, GPL-3.0-or-later, or MIT OR Apache-2.0.
• Deprecated GNU-style identifiers such as GPL-3.0 and GPL-3.0+ are accepted as a convenience and normalized to modern SPDX identifiers such as GPL-3.0-only and GPL-3.0-or-later.
• A trailing + may be used for "or later" style expressions where applicable, e.g., EUPL-1.2+.
• Reuse writes parsed and normalized SPDX expressions to REUSE.toml. License and exception texts copied to LICENSES/ are selected from the SPDX identifiers referenced by those expressions.
• Custom license texts may be referenced with LicenseRef-... identifiers. The corresponding text must be provided in license_ref_dir.

License Approval Checking

license_approval must be one of the following strings: "code", "strict", "none". The behavior is:

• license_approval="code" requires that the primary code license expression has an OSI-approved path according to the bundled SPDX License List metadata. For example, MIT OR LicenseRef-X passes because the expression provides an OSI-approved path. WITH exceptions are rejected here for now, as a conservative interpretation.
• license_approval="strict" includes the requirements of "code" and additionally requires all other license expressions to have either an OSI-approved or FSF-libre path according to the bundled SPDX metadata. For example, CC-BY-NC-4.0 would fail.
• license_approval="none" disables OSI/FSF-libre approval checks and allows the broadest REUSE-compliant setup, including custom LicenseRef-* licenses and license exceptions.

user_view(::Plugin, ::Template, pkg::AbstractString) -> Dict{String, Any}

The same as view, but for use by package users for extension.

Values returned by this function will override those from view when the keys are the same.