Skip to content

project¤

Manage projects (GitHub and local copies).

create¤

Create public/insiders repositories.

This command will do several things:

  • Create public and insiders repositories on GitHub (using the provided namespace, username, repository name, description, etc.).
  • Clone these two repositories locally (using the provided repository paths).
  • Optionally initialize the public repository by generating initial contents using the specified Copier template and answers.
  • Optionally run a post creation command into the public repository.
  • Pull the public contents into the insiders clone (by declaring an upstream remote).

Example 1 - Project in user's namespace

The insiders namespace, insiders repository name and username are inferred from the namespace and repository name.

insiders create \
    -n user \
    -r mkdocs-ultimate \
    -d "The ultimate plugin for MkDocs (??)" \
    -o ~/data/dev \
    -O ~/data/dev/insiders \
    -t gh:user/copier-uv

Example 2 - Project in another namespace:

The insiders namespace, insiders repository name and username are different, so must be provided explicitly:

insiders create \
    -n mkdocstrings \
    -r rust \
    -d "A Rust handler for mkdocstrings" \
    -o ~/data/dev \
    -O ~/data/dev/insiders \
    -N user-insiders \
    -R mkdocstrings-rust \
    -u user \
    -t gh:mkdocstrings/handler-template
Options Description Default
-r, --repository REPOSITORY Name of the public repository.
-d, --description DESCRIPTION Shared description.
-n, --namespace NAMESPACE Namespace of the public repository. project.namespace config-value
-o, --project-directory PROJECT_DIRECTORY Directory in which to clone the public repository. project.directory config-value
-R, --insiders-repository INSIDERS_REPOSITORY Name of the insiders repository. public name
-N, --insiders-namespace INSIDERS_NAMESPACE Namespace of the insiders repository. project.insiders-namespace config-value or public namespace
-O, --insiders-project-directory INSIDERS_PROJECT_DIRECTORY Directory in which to clone the insiders repository. project.insiders-directory config-value
-u, --github-username GITHUB_USERNAME GitHub username. project.github-username config-value or public namespace
-t, --copier-template COPIER_TEMPLATE Copier template to generate new projects with. project.copier-template config-value
-a, --copier-template-answers COPIER_TEMPLATE_ANSWERS Copier template answers to use when generating a project. project.copier-template-answers config-value
-x, --post-creation-command POST_CREATION_COMMAND Command to run after creating the public repository. project.post-creation-command config-value
-i, --register-on-pypi Whether to register the project on PyPI after creating it. project.register-on-pypi config-value
-y, --pypi-username PYPI_USERNAME PyPI username to register the project with. project.pypi-username config-value

check¤

Check public/insiders repositories.

TODO. Check that everything is consistent.

register-pypi¤

Register a name on PyPI.

This will create a temporary project on your filesystem, then build both source and wheel distributions for it, and upload them to PyPI using Twine.

After that, you will see an initial version 0.0.0 of your project on PyPI.

Example

insiders pypi register -u user -n my-new-project -d "My new project!"

Credentials must be configured in ~/.pypirc to allow Twine to push to PyPI. For example, if you use PyPI API tokens, add the token to your keyring:

pipx install keyring
keyring set https://upload.pypi.org/legacy/ __token__
# __token__ is a literal string, do not replace it with your token.
# The command will prompt you to paste your token.

And configure ~/.pypirc:

[distutils]
index-servers =
    pypi

[pypi]
username: __token__
Options Description Default
-u, --username USERNAME Username on PyPI (your account). project.pypi-username config-value
-n, --name NAME Name to register.
-d, --description DESCRIPTION Description of the project on PyPI.