Getting started
You must have Python 3.7 or later, and a relatively recent version of Git. Git 2.30 is known to work, but older versions will most likely work as well.
Installation
It is recommended to install Cogite within a Python virtual environment. If you are not familiar with that, the following should do the trick:
$ mkdir --parents ~/.venv
$ python3 -m venv ~/.venv/cogite
$ ~/.venv/cogite/bin/pip install --upgrade pip cogite
$ alias cogite="~/.venv/cogite/bin/cogite"
This may not be optimal but should let you start right away.
Minimal configuration
Move to the directory where you have a checkout of a Git repository.
Run
cogite auth add
and follow instructions.FIXME: explain the two current options : manual token or automatic configuration.
For further details about authentication-related commands, see Authentication and cogite auth.
That’s it, you are ready to use Cogite.
How to use
Here we describe how to use Cogite in a feature branch workflow (even though Cogite could work with other workflows).
Create your feature branch with
git checkout -b new-feature
.Work on your branch and create commits as you usually do.
When ready, create a pull request with
cogite pr add
.The command will guide you through, proposing to modify the title and the description of the pull request, and asking whether you want to select reviewers.
Here is an example output:
$ cogite pr add ✔ Pushed local branch to upstream. Confirm title and body: | Update README Continue [Y/e/n]? ✔ Created pull request on Git host Reviewers (leave blank if none, tab to complete, space to select, enter to validate): Created #21 at https://github.com/dbaty/sandbox/pull/21
For further details, see cogite pr add.
If you use a supported CI platform (such as CircleCI or GitHub Actions), you can show their status with
cogite status
. This command also shows the status of each review. Here is an example output:$ cogite status Checks: ✔ ci/circleci: Run quality checks (https://circleci.com/gh/dbaty/sandbox/11670 ✔ ci/circleci: Run tests (https://circleci.com/gh/dbaty/sandbox/11671 Reviews: … jsmith
For further details, see cogite status.
When ready to merge this pull request, run
cogite pr merge
. Here is an example output:$ cogite pr merge You are about to rebase new-feature on master and push master upstream. Continue [y/N]? y ✔ git checkout master ✔ git pull --rebase ✔ git checkout new-feature ✔ git rebase master ✔ git push --force-with-lease ✔ git checkout master ✔ git rebase new-feature ✔ git push ✔ git branch --delete new-feature ✔ git push --delete origin new-feature ✔ Your pull request has been merged to master and the corresponding branches (local and upstream) have been deleted.
As you can see, Cogite shows exactly what it does. If the process fails at some point, you can always rollback local changes or fallback to manual operations.
For further details, see What Cogite does when merging and cogite pr merge.