Contents

• Installation
• Initial Setup
• Usage
  • Repositories
    • List
    • Create
    • Edit
    • Delete
    • Collaborators
      • List
        • Inactive
      • Add
      • Remove
    • Commits
      • List
  • Branches
    • List
    • Create
    • Rename
    • Delete
    • ⚠️ Branch Protection
      • Set
      • Remove
  • Modules
    • Basic Command
• FAQ
  • Option Types

Installation

It is possible to install git-admin through NPM or Yarn.

# An example of installing using NPM
npm i -g git-admin

# An example of installing using Yarn
yarn global add git-admin

Initial Setup

Before you can do anything through git-admin you must create a personal access token. You can create one by going here, find out more here.

As git-admin's functionality is currently based around repositories you will need to tick the repo checkbox, and if you want to be able to delete repos then tick the delete_repo checkbox.

More featured are in the works, so you will have to update the token in the future.

After creating a personal access token you will be presented with a code. Run the following command to store it:

# An example of setting the personal access token
git-admin config token <personal-access-token>

Usage

Repositories

When editing or deleting a repository a confirmation prompt will appear before taking any action. Although not recommended the prompt can be skipped by adding --force (or -f, --yes, or -y).

List

To list repositories for your account simply run:

# An example of listing personal repositories
git-admin repo list

If you want to get all the repos that are visible to you for another user run:

# An example of listing another user's repositories
git-admin repo list --user user

If you want to get all the repos that are visible to you for an organization run:

# An example of listing an organization's repositories
git-admin repo list --org organization

Options

All options are optional.

• --organization, --org, -o
  • String
• --user, -u
  • String
• --page, -p
  • Number (default 1)

Organization Options

• --type, -t
  • all (default), public, private, fork, sources, member

User Options

• --type, -t
  • all (default), owner, member
• --sort, -s
  • created, updated, pushed, full_name (default)
• --direction, -d
  • asc, desc

Personal options

• --type, -t
  • all (default), owner, public, private, member
• --visibility, -v
  • all (default), public, private
• --affiliation, -a
  • One or combined of: owner, collaborator, organization_member (default all combined)

User options included

Create

To create a repository for your account simply run:

# An example of creating a personal public repository
git-admin repo create awesome-new-project

Depending on if you are an administrator to any organizations will determine if you are able to create organization repositories.

# An example of creating a public organization repository. The private option can also be applied here
git-admin repo create organization/awesome-new-project

Options

All options are optional.

• --private, -p
  • Boolean

Edit

To edit a repository for your account simply run:

# An example of editing a personal repository
git-admin repo edit user/awesome-new-project

Depending on if you are an administrator to any organizations will determine if you are able to edit organization repositories. It's worth noting that even if the new name is prefixed with an organization then only the repository name will be used ([organization/]repository).

Options

All options are optional.

• --name, -n
  • String
• --description, --desc, -d
  • String
• --homepage, --url
  • String
• --private, -p
  • Boolean
• --default-branch
  • String

Delete

Deleting repositories require the delete_repo scope. To delete a repository for your account simply run:

# An example of deleting a personal repository
git-admin repo delete user/repository

Similarly if you are an organization repository admin then you can also delete organization repositories.

Collaborators

List

To list collaborators for a repository simply run:

# An example of listing collaborators for a repository
git-admin repo user list user/repository

Options

• --page, -p
  • Number (default 1)

List Inactive

To find inactive users for a repository simply run:

# An example of finding all inactive collaborators, who haven't commited in a month, to a repository
git-admin repo user inactive user/repository

If you have admin permissions on a repository you can also use --prune to automatically remove any users found:

# An example of finding all inactive collaborators, who haven't commited in a month, to a repository and removing them automatically
git-admin repo user inactive user/repository --prune

Options

• --sha, --branch, -b
  • String (default master)
• --until, --before, -u
  • Date (default previous month from current date), expected format: MM-DD-YYYY. Check out dayjs for more parsing information
• --prune, -p
  • Boolean

Add

To add a collaborator to your repository simply run:

# An example of adding a collaborator to a personal repository
git-admin repo user add userB user/repository

If you are an organization repository admin you can also do this for organization repositories.

Options

All options are optional.

• --permissions, --perms, --perm, -p
  • pull, push (default), admin

Remove

To remove a collaborator to your repository simply run:

# An example of removing a collaborator to a personal repository
git-admin repo user remove userB user/repository

If you are an organization repository admin you can also do this for organization repositories.

Commits

List

To list commits for a repository simply run:

# An example of listing commits for a repository
git-admin repo commits list user/repository

Options

• --page, -p
  • Number (default 1)
• --sha, --branch, -b
  • String (default master)
• --path
  • String
• --author, --user, -u
  • String
• --since, --after
  • String (default current date), expected format: MM-DD-YYYY. Check out dayjs for more parsing information
• --after, --before
  • String, expected format: MM-DD-YYYY. Check out dayjs for more parsing information

Branches

When renaming or deleting a branch a confirmation prompt will appear before taking any action. Although not recommended the prompt can be skipped by adding --force (or -f, --yes, or -y).

List

To list branches for a repository simply run:

# An example of listing branches for a repository
git-admin branch list user/repository

Options

All options are optional.

• --page, -p
  • Number (default 1)

Create

To create a branch for a repository simply run:

# An example of creating a branch for a repository
git-admin branch create user/repository new-branch

To create a branch based off another branch simply run:

# An example of creating a branch based off a different branch for a repository
git-admin branch create user/repository production --base-branch staging

Options

All options are optional.

• --base-branch, -b
  • String (default master)

Rename

To rename a branch for a repository simply run:

# An example of renaming a branch for a repository
git-admin branch rename user/repository original renamed

⚠️ Remember that this is remotely renaming branches, not locally.

Delete

To delete a branch for a repository simply run:

# An example of deleting a branch for a repository
git-admin branch delete user/repository old-branch

⚠️ Remember that this is remotely deleting branches, not locally.

Options

All options are optional.

• --branches, -b
  • Array

Branch Protection

⚠️ Branch protection API is current in preview mode (pre-release). So the following commands should be considered unstable.

When changing repository settings a confirmation prompt will appear before taking any action. Although not recommended the prompt can be skipped by adding --force (or -f, --yes, or -y).

Set

To set branch protection for a branch simply run:

# An example of setting protection on a branch
git-admin branch protection set user/repository master

If you want to set protection for multiple branches simply run:

# An example of setting branch protection on multiple branch
git-admin branch protection set user/repository --branches master staging production

Options

All options are optional.

• --strict-status-checks, --strict, --srsc, --ssc
  • Boolean
• --status-checks, --contexts, --rsc, --sc
  • Array
• --dismissal-restrict-users, --dru
  • Array
• --dismissal-restrict-teams, --drt
  • Array
• --code-owner-review, --owner-review, --code-owner, --rcor, --or, --co
  • Boolean
• --approving-review-count, --review-count, --arc, --rc
  • Number
• --restrict-users, --ru
  • Array
• --restrict-teams, --ru
  • Array
• --enforce-admins, --ea
  • Boolean
• --branches, -b
  • Array

Remove

To remove branch protection for a branch simply run:

# An example of removing branch protection on a branch
git-admin branch protection set user/repository master

If you want to remove protection for multiple branches simply run:

# An example of removing branch protection on multiple branches
git-admin branch protection set user/repository --branches master staging production

Options

All options are optional.

• --branches, -b
  • Array

Modules

Modules allow git-admin to be extended easily. git-admin looks for a directory in your home directory:

# Node's `os.homedir` is used for finding your home directory
$HOME/.git-admin/modules

Within the modules directory git-admin checks for any directories and attempts to require them, because of this you are able to create whatever commands with whatever complexity you want. Check out Yarg's command module documentation.

Modules should follow a naming convention as restriction may need to be added in the future.

git-admin-module-[module-name]

Just make sure that your package.json main is pointing to the entrypoint for your command(s).

Basic Command:

// An example of a barebones command
// $HOME/.git-admin/modules/git-admin-module-example/index.js

exports.command = 'example';
exports.desc = 'Example module command';

exports.handler = () => console.warn('hello, world');

FAQ

Option Types

When describing an option for a command, under the aliases, there is a type. These reference a yargs option type.

• Array
• Boolean
• Count
• Number
• String