git-circle
git-circle is a git extension which provides CLI interaction with
your builds on CircleCI.
Installation
git-circle requires Python (>=2.7), with requests and colorama.
Install git-circle with pip:
pip install git-circle
# -or- to install for an individual user
pip install --user git-circle
git-circle General Usage
usage: git-circle [-h] [-v] [-np] [-l] [-s] [-ar] [-al] [--limit LIMIT]
[--today] [--yesterday] [-d DATE] [-y] [-m]
[command] [param]
positional arguments:
command The command to run
param Optional param for commands, see commands list for
more information
optional arguments:
-h, --help show this help message and exit
-v, --verbose Run verbosely
-np, --no-page Disable paging
-l, --list List the commands available
-s, --stats Display useful stats at the end
-ar, --all-remote Filter by all remote branches (not all commands
support this)
-al, --all-local Filter by all local branches (not all commands support
this)
--limit LIMIT Change the default limit for the underlying CircleCI
API call (default 30, max 100)
--today Limit responses to just those from today (not all
commands support this)
--yesterday Limit responses to just those from yesterday (not all
commands support this)
-d DATE, --date DATE Limit responses to just those from a certain date,
format YYYY-MM-DD (not all commands support this)
-y, --yes Automatically answer all queries with a 'yes'
-m, --machine Output the results in a machine readable way
git-circle Commands
list-projects
This command will list the projects you are following, along with their branches which have run and the statuses of the most recent builds.
Usage:
git circle list-projects [-v] [-np]
latest
This command will display the results of the latest build for your current branch.
Usage:
git circle latest [-v] [-np]
build
This command will display the results of a given build. If called with a build number, will use that build. If called without a build number, will use the latest build for your current branch.
Usage:
git circle build [build_number] [-v] [-np]
list-builds
This command will list the recent builds for a given branch. If called with a branch name, will find the recent builds for that branch. If called without a branch name, will use the current branch.
Usage:
git circle list-builds [branch_name] [-v] [-np] [-s] [-ar] [-al] [--limit] \
[--today] [--yesterday] [--date DATE]
The following options have special meanings for list-builds:
-
-s/--stats: Will display useful statistics at the end. -
-ar/--all-remote: Will cycle through all of the branches in the remote git repo and list the recent builds for each. WARNING: This could, potentially, be a lot of branches. Use with caution. -
-al/--all-local: Will cycle through all of the branches in the local git repo and list the recent builds for each. WARNING: This could, potentially, be a lot of branches. Use with caution. -
--limit: Change the default limit for the number of recent builds to obtain from CircleCI. The default is 30, and the maximum is 100. -
--today: Limit the recent builds to only those with today's date. -
--yesterday: Limit the recent builds to only those with yesterday's date. -
--date: Limit the recent builds to only those found on a given date. The date format is YYYY-MM-DD.
new-build
This command will trigger a new build for a given branch. If called with a branch name, will use that for the new build. If called without a branch name, will use the current branch.
This command will prompt you for comfirmation of the build, unless you specify
the -y/--yes option.
Usage:
git circle new-build [branch_name] [-v] [-np] [-y]
cancel
This command will cancel a build. If called with a build number, will cancel that build. If called without a build number, will use the latest build for the current branch.
This command will prompt you for confirmation of the cancellation, unless you
specify the -y/--yes option.
Usage:
git circle cancel [build_number] [-v] [-np] [-y]
retry
This command will retry a build. If called with a build number, will attempt to retry that build. If called without a build number, will use the latest build for the current branch.
This command will prompt you for confirmation of the retry, unless you specify
the -y/--yes option.
Usage:
git circle retry [build_number] [-v] [-np] [-y]
artifacts
This command will display the build artifacts for a given build. If called with a build number, it will display the artifacts for that build. If called without a build number, it will display the artifacts for the last build of the current branch.
The artifacts will be grouped by CircleCI nodes (see
here) and will, by default,
display the artifacts as they would be found on the nodes. If called with the
-v/--verbose option then the full artifact path as well as the artifact
URL will also be displayed.
Usage:
git circle artifacts [build_num] [-v] [-np] [-s] [-ar] [-al]
The following options have special meanings for artifacts:
-
-s/--stats: Will display useful statistics at the end, grouped by branches. -
-ar/--all-remote: Will cycle through all of the branches in the remote git repo and display the artifacts for each. WARNING: This could, potentially, be a lot of branches. Use with caution. -
-al/--all-local: Will cycle through all of the branches in the local git repo and display the artifacts for each. WARNING: This could, potentially, be a lot of branches. Use with caution.
Using git-circle in scripts
git-circle, by default, is a
porcelain
utility, meaning it is intended to be consumed by a user.
However, if you want to use git-circle as a source of data for processing
elsewhere, we do provide the -m/--machine option for generating machine
readable output.
For more information, see MACHINE_READABLE
