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.

_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.

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

• :testitem_cli - regenerates test/runtests.jl with the testitem_cli testing strategy
• :pre_commit_with_config - regenerates .pre-commit-config.yaml and formatter/linter config files
• :pre_commit_without_config - regenerates only .pre-commit-config.yaml
• :pre_commit - alias for :pre_commit_with_config
• :lint_action - regenerates .github/workflows/Lint.yml (requires .copier-answers.yml)
• :dependabot - regenerates .github/dependabot.yml (requires PackageName)
• :changelog - regenerates CHANGELOG.md (requires PackageOwner and PackageName)

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

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