Reference

BestieTemplate.jl

This package defines a copier template for Julia packages and a basic user interface around copier to use it from Julia.

The main functions are: generate, apply, and update.

To create a new package using BestieTemplate run

julia> BestieTemplate.generate("path/to/YourNewPackage.jl")

To apply the template to an existing package

julia> BestieTemplate.apply("path/to/YourExistingPackage.jl")

Check the documentation: https://JuliaBesties.github.io/BestieTemplate.jl

_copy(src_path, dst_path, data; kwargs...)

Internal function to run common code for new or existing packages.

_feature_spec(features, feature::Symbol)

Look up feature in the registry loaded by _load_features, resolving aliases.

_features_docstring(registry_path = BUNDLED_FEATURES_TOML)

Generate the supported-features list of the add_feature docstring from a features.toml registry, the bundled one by default. A problem with the registry must not prevent the module from loading, so on error this degrades to a pointer to the file (the registry is validated by the test suite instead).

_load_copier_answers(path)

Read a .copier-answers.yml file and return the parsed Dict.

Overrides YAML's float tag to keep _commit values that would otherwise be parsed as a float (e.g. 64e3774 = 64.0 * 10^3774, a git short SHA copier wrote unquoted) as strings.

_load_features(registry_path = BUNDLED_FEATURES_TOML)

Load the feature registry (features.toml) used by add_feature. If registry_path does not exist (e.g. a frozen local template copy predating the registry), fall back to the bundled copy.

data = _read_data_from_existing_path(dst_path)

Reads the destination folder to figure out some answers.

_resolve_template(; template_source, local_template_path, use_latest) -> (path, change_permissions, extra_args)

Resolve the template path and extra arguments from user-friendly keywords.

package_name = _sanitize_package_name(path)

Sanitize the path to guess the package_name by looking at the base name and removing an extension. If the result is not a valid identifier, returns "".

add_feature(feature::Symbol[, dst_path, data]; kwargs...)

Add or regenerate a specific feature's template files for an existing package.

Reads .copier-answers.yml (if present) and guesses data from the package, then applies only the files relevant to feature. If .copier-answers.yml exists, it is updated; otherwise no answers file is created.

Supported features

Features are defined in the features.toml registry shipped with the template (the list below is generated from the bundled copy; a custom local_template_path may provide its own registry):

• :agents: Adds AGENTS.md with guidance for AI coding agents; an existing AGENTS.md is kept unchanged. Requires PackageName.
• :changelog: Adds CHANGELOG.md following the Keep a Changelog format. Requires PackageOwner and PackageName.
• :dependabot: Adds .github/dependabot.yml with auto-updates for GitHub Actions versions and Julia compat entries. Requires PackageName.
• :lint_action: Adds the .github/workflows/Lint.yml GitHub Actions workflow. Requires .copier-answers.yml.
• :pre_commit: Alias for :pre_commit_with_config.
• :pre_commit_with_config: Adds .pre-commit-config.yaml and the formatter/linter configuration files.
• :pre_commit_without_config: Adds only .pre-commit-config.yaml, without the formatter/linter configuration files.
• :testitem_cli: Updates test/runtests.jl to the testitem_cli testing strategy (filterable CLI test runner). Follow-up migration needed: existing tests must move to @testitem blocks and test/Project.toml must exist with the test dependencies (including TestItemRunner).

Arguments

• feature::Symbol: Which feature to apply.
• dst_path: Path to the existing package. Default: ".".
• data: Optional dictionary of additional data to merge. Default: Dict().

Keyword arguments

• local_template_path: Template path to use when template_source = :local. Default: pkgdir(BestieTemplate).
• template_source::Symbol: Source of the template, either :local or :online. :local uses the path of the BestieTemplate package as given by the keyword local_template_path, and :online uses the GitHub URL. Notice that using :local will freeze the version to a folder, so manual update is necessary.
• use_latest::Bool: Whether to use the latest commit of the template (otherwise use the last release). Default: false.
• Additional keyword arguments are passed to Copier.copy.

apply(dst_path[, data]; kwargs...)
apply(local_or_online, dst_path[, data]; kwargs...)
apply(src_path, dst_path[, data]; kwargs...)

Applies the template to an existing project at path $dst_path$. If the dst_path does not exist, this will throw an error. For new packages, use BestieTemplate.generate instead.

Runs the copy command of copier with the BestieTemplate template, with overwrite = true. If src_path is not informed, the GitHub URL of BestieTemplate.jl is used.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

• guess:Bool = true: Whether to try to guess some of the data from the package itself.
• warn_existing_pkg::Bool = true: Whether to check if you actually meant update. If you run apply and the dst_path contains a .copier-answers.yml, it means that the copy was already made, so you might have means update instead. When true, a warning is shown and execution is stopped.
• quiet::Bool = false: Whether to print greetings, info, and other messages. This keyword is also used by copier.
• change_permissions::Boolean = false: Whether to change the permissions of the destination project.

The other keyword arguments are passed directly to the internal Copier.copy.

change_project_permissions(project_path)

Change the permission of all files in the project_path to 644 and folders to 755.

generate(dst_path[, data]; kwargs...)
generate(local_or_online, dst_path[, data]; kwargs...)
generate(src_path, dst_path[, data]; kwargs...)

Generates a new project at the path dst_path using the template. If the dst_path already exists, this will throw an error, unless dst_path = ".". For existing packages, use BestieTemplate.apply instead.

Runs the copy command of copier with the BestieTemplate template.

local_or_online can be either :local or :online. If it is :online, the GitHub URL of BestieTemplate.jl is used. Otherwise, the pkgdir(BestieTemplate) is used.

If src_path is informed an URL or a path to a compatible template is expected.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions. See https://juliabesties.github.io/BestieTemplate.jl/stable/30-questions/ for a list all questions.

Keyword arguments

• warn_existing_pkg::Boolean = true: Whether to check if you actually meant update. If you run generate and the dst_path contains a .copier-answers.yml, it means that the copy was already made, so you might have means update instead. When true, a warning is shown and execution is stopped.
• quiet::Boolean = false: Whether to print greetings, info, and other messages. This keyword is also used by copier.
• change_permissions::Boolean = false: Whether to change the permissions of the generated project.

The other keyword arguments are passed directly to the internal Copier.copy.

new_pkg_quick(
    pkg_destination,
    package_owner,
    authors,
    strategy::Symbol,
    extra_data = Dict();
    license = "MIT",
    local_template_path = pkgdir(BestieTemplate),
    template_source = :online,
    use_latest = false,
    kwargs...;
)

Creates a new package using defaults and no interaction.

Convenience function that requires the least amount of information to generate a package using the "Tiny" strategy.

Arguments

• pkg_destination: Path to the folder where the package will be created. Examples: "NewPkg.jl", ".", "~/.julia/dev/NewPkg.jl"
• package_owner: GitHub username or organization that owns the package (This will be used for URLs). Examples: "JuliaBesties", "username"
• authors: Package authors separated by commas (We recommend the form "NAME <EMAIL>", but this can be ignored). Examples: "JuliaBesties maintainers", "Alice <alice@alice.com>, Bob <bob@bob.nl>"
• strategy::Symbol: Which strategy to use. Values: :tiny, :light, :moderate, and :robust
• extra_data: Dictionary with extra data to be added to the answers file. Default: Dict(). Examples: Dict("AddDocs" => true). See the Questions section for all the options.

Keyword arguments

• license: Which license to add. Default: MIT. Choices: "Apache-2.0", "GPL-3.0", "MIT", "MPL-2.0", "nothing".
• local_template_path: Template path to use when template_source = :local. Default: pkgdir(BestieTemplate).
• template_source::Symbol: Source of the template, either :local or :online. :local uses the path of the BestieTemplate package as given by the keyword local_template_path, and :online uses the GitHub URL. Notice that using :local will freeze the version to a folder, so manual update is necessary.
• use_latest::Bool: Whether to use the latest commit of the template (otherwise use the last release). Default: false.
• Additional keyword arguments are passed directly to generate.

update([data]; kwargs...)
update(dst_path[, data]; kwargs...)

Run the update command of copier, updating the dst_path (or the current path if omitted) with a new version of the template with a new version of the template.

The data argument is a dictionary of answers (values) to questions (keys) that can be used to bypass some of the interactive questions.

Keyword arguments

The keyword arguments are passed directly to the internal Copier.update.

Wrapper around copier.

There are three functions in this module:

• copy
• recopy
• update

_copier_tempdir_from_exception(ex)

If ex is Copier failing to remove its own temporary VCS clone, return the path of that temporary clone. Otherwise, return nothing.

_ignore_cleanup_race(f)

Run f(), ignoring failures from Copier's cleanup of its temporary VCS clone.

Copier removes its temporary clone only after the requested operation has fully completed, and on Linux that shutil.rmtree intermittently fails with OSError: [Errno 39] Directory not empty. The destination files are already in place at that point, so the operation is treated as successful and the leftover temporary clone is removed here instead.

copy(dst_path[, data]; kwargs...)
copy(src_path, dst_path[, data]; kwargs...)

Wrapper around copier.run_copy.

This is an internal function, if BestieTemplate's main API is not sufficient, open an issue. Note: this is not Base.copy, inside the Copier module we shadow that name.

recopy(dst_path[, data]; kwargs...)

Wrapper around copier.run_recopy.

This is an internal function, if BestieTemplate's main API is not sufficient, open an issue.

update(dst_path[, data]; kwargs...)

Wrapper around copier.run_update.

This is an internal function, if BestieTemplate's main API is not sufficient, open an issue.

Module Debug

Tools for debugging Bestie. Nothing here is public API.

Noteworthy: BestieTemplate.Debug.Data

dbg_apply([dst_path, data]; data_choice=:minimum)

Convenience function to help debug apply. It runs apply with the dst_path destination and the given data (nothing by default).

It also uses a data_choice to determine fake starting data. This is passed to dbg_data.

It uses the pkgdir location of Bestie and adds the flags

• defaults = true: Sent to copier to use the default answers.
• quiet = true: Low verbosity.
• overwrite = true: Overwrite all files.
• vcs_ref = HEAD: Use the development version of the template, including dirty repo changes.

dbg_data(data_choice, more_data)

Returns the fake debug data merged with more_data. The options for data_choice are:

• :nothing, :none: No random data.
• :required, :req: Only the required data is generated. You get asked which choice of optional data.
• :minimum, :min: The required data plus the choice "minimum" for optional data.
• :recommended, :rec: The required data plus the choice "recommended" for optional data.
• :ask: The required data plus the choice "ask". The optional questions will be asked.
• :ask_default: Same as :ask plus the default answers for the optional questions.
• :ask_and_say_no: Same as :ask plus answers no/false to the optional questions.
• :ask_and_say_yes: Same as :ask plus answers yes/true to the optional questions.

dbg_generate([dst_path, data]; data_choice=:minimum)

Convenience function to help debug generate.

It runs generate with the dst_path destination (random by default) and the given data (nothing by default).

It also uses a data_choice to determine fake starting data. This is passed to dbg_data.

This function can be called in multiple ways:

• dbg_generate(): Use all defaults
• dbg_generate(my_data::Dict): Use my_data and all defaults
• dbg_generate(dst_path::String): Use dst_path and all defaults
• dbg_generate(data_choice::Symbol): Use all defaults and data_choice to generate my_data

It uses the pkgdir location of Bestie and adds the flags

• defaults = true: Sent to copier to use the default answers.
• quiet = true: Low verbosity.
• vcs_ref = HEAD: Use the development version of the template, including dirty repo changes.

Fake data for testing

• Debug.Data.strategies: NamedTuple of Dictionaries with default data