Git Admin
git-admin
is a node package that makes it easier to manage GitHub repositories, through commandline.
Contents
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
)
- Number (default
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)
- One or combined of:
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
)
- Number (default
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
)
- String (default
--until
,--before
,-u
- Date (default previous month from current date), expected format:
MM-DD-YYYY
. Check out dayjs for more parsing information
- Date (default previous month from current date), expected format:
--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
)
- Number (default
--sha
,--branch
,-b
- String (default
master
)
- String (default
--path
- String
--author
,--user
,-u
- String
--since
,--after
- String (default current date), expected format:
MM-DD-YYYY
. Check out dayjs for more parsing information
- String (default current date), expected format:
--after
,--before
- String, expected format:
MM-DD-YYYY
. Check out dayjs for more parsing information
- String, expected format:
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
)
- Number (default
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
)
- String (default
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
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
Options
All options are optional.
--branches
,-b
- Array
Branch Protection
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.