Getting started¶
Installation¶
Githubcutter can be installed through pip by running:
pip install githubcutter
Githubcutter requires a .githubcutter.env file to store your GitHub authentication token; for example, you can put this file in your home directory.
Create a new .githubcutter.env file and put the line below:
GITHUBCUTTER_GITHUB_TOKEN=<token>
replacing <token> with the one you obtained from GitHub.
If Githubcutter is properly installed, running without parameters should print:
usage: githubcutter [-h]
{create-repository,cr,create,delete-repository,dr,delete,list-repositories,ls,list}
...
Basic usage¶
Creating a new repository¶
Githubcutter can create repositories on personal and/or organisation accounts using a YAML template. This streamlines the process of creating repositories, specificying basic info, creating custom labels, and adding milestones.
The template file looks like the one below, and the field names match the one expected by the Github API.
# repository
repository: "testing"
# basic repository setting
settings:
# is the repo private?
private: True
# description
description: "a new repo"
# homepage
homepage: "https://github.com"
# enable wiki
has_wiki: True
# enable issues
has_issues: True
# custom labels
labels:
- name: "High-priority"
color: "000"
description: "high-priority task for the project"
- name: "Low-priority"
color: "fff"
description: "low-priority task for the project"
# custom milestones
milestones:
- title: "ML #1"
state: "open"
description: "Important milestone for the project"
due_on: 01-01-2020
- title: "ML #2"
state: "open"
description: "Important milestone for the project"
due_on: 01-01-2020
Githubcutter looks for a githubcutter.yml fiel by default. Therefore, creating a repo can be as easy as running:
githubcutter create
It is also possible to specify an arbitrary template file as follows:
githubcutter create -i myfile.yml
Specify an organization¶
By default, githubcutter creates a repository in the personal account associated with the GitHub token.
You can instead specify an organisation in the template file as follows:
# repository
repository: "testing"
organization: "myteam"
...
or by using the command line option:
githubcutter create -o myteam
Specifying repository access¶
You can specify the access level in the template file as follows:
# repository
repository: "testing"
settings:
private: True
...
or by using the command line option:
githubcutter create -p
Important¶
Githubcutter prioritizes options specified by command line over those specified in the template file.
For example, it is possible to reuse the same template for multiple repositories as follows:
githubcutter create -r my_new_app -i template.yml
Listing repositories¶
It is possible to list repositories on a personal account or organization as follows:
githubcutter ls
Deleting repositories¶
It is possible to list repositories on a personal account or organization as follows:
githubcutter delete testing
Adding labels¶
It is possible to add labels to an existing repository from a template as follows:
githubcutter add-labels -i template.yaml -r test