README.md in git-semaphore-0.0.9 vs README.md in git-semaphore-1.0.0
- old
+ new
@@ -1,84 +1,210 @@
# Git::Semaphore
-[](https://semaphoreci.com/pvdb/git-semaphore)
+[](https://semaphoreci.com/pvdb/git-semaphore)
[](https://travis-ci.org/pvdb/git-semaphore)
-git integration with [semaphoreci.com][] (via their API)
+Integrate git repositories with their corresponding project on [semaphoreci.com][] _(via the semaphore API)_
+## Features
+
+* highly opiniated
+* integrated with `git`
+* caching of API results
+* pagination of API calls
+* enrichment of API data
+* extensive API feature support
+* support for multiple Semaphore accounts
+
+## Semaphore API support
+
+The following sections of the [Semaphore API][] are fully or partially supported by `git semaphore`:
+
+| API section | | summary |
+|--------------------|----|---------|
+| [authentication][] | ✅ | API authentication |
+| [projects][] | ✅ | listing projects |
+| [branches and builds][] | ✅ | querying branches and managing builds |
+| [servers and deploys][] | ❌ | querying servers and managing deploys |
+| [webhooks][] | ❌ | listing and managing webhooks |
+
+[authentication]: https://semaphoreci.com/docs/api_authentication.html
+[projects]: https://semaphoreci.com/docs/projects-api.html
+[branches and builds]: https://semaphoreci.com/docs/branches-and-builds-api.html
+[servers and deploys]: https://semaphoreci.com/docs/servers-and-deploys-api.html
+[webhooks]: https://semaphoreci.com/docs/webhooks-api.html
+
+The following [Semaphore API][] features are supported by `git semaphore`:
+
+| API feature | | command |summary |
+|------------------|----|---------|--------|
+| [authentication][] | ✅ | | provide user authentication via an authentication token |
+| [projects][] | ✅ | `git semaphore --projects` | list all projects and their current status |
+| [project branches][] | ✅ | `git semaphore --branches` | list all branches for the current project |
+| [branch status][] | ✅ | `git semaphore --status` | list the build status for the current branch |
+| [branch history][] | ✅ | `git semaphore --history` | list the build history for the current branch |
+| [build information][] | ❌ | | detailed information for a given build number |
+| [build log][] | ❌ | | execution logs for a given build number _(per thread and command)_ |
+| [rebuild][] | ✅ | `git semaphore --rebuild` | rebuild last revision for the current branch |
+| [launch build][] | ❌ | | launch a build for the given commit SHA |
+| [stop][] | ❌ | | stop an in-progress build |
+| [deploy][] | ❌ | | run a deploy from a given build |
+
+[project branches]: https://semaphoreci.com/docs/branches-and-builds-api.html#project_branches
+[branch status]: https://semaphoreci.com/docs/branches-and-builds-api.html#branch_status
+[branch history]: https://semaphoreci.com/docs/branches-and-builds-api.html#branch_history
+[build information]: https://semaphoreci.com/docs/branches-and-builds-api.html#build_information
+[build log]: https://semaphoreci.com/docs/branches-and-builds-api.html#build_log
+[rebuild]: https://semaphoreci.com/docs/branches-and-builds-api.html#rebuild
+[launch build]: https://semaphoreci.com/docs/branches-and-builds-api.html#launch_build
+[stop]: https://semaphoreci.com/docs/branches-and-builds-api.html#stop
+[deploy]: https://semaphoreci.com/docs/branches-and-builds-api.html#deploy
+
## Installation
-Add this line to your application's Gemfile:
+Install the gem:
- gem 'git-semaphore'
+ gem install git-semaphore
-And then execute:
+And execute it as a `git` subcommand:
- $ bundle
+ git semaphore <options>
-Or install it yourself as:
+To get an overview of the available options, use:
- $ gem install git-semaphore
+ git-semaphore --help
-## Authentication
+## API authentication
-Log into [semaphoreci.com][] and find your API `authentication token` in the `API` tab of one of your projects' `settings` page.
+Log into [semaphoreci.com][] and find **your authentication token** at the bottom of your [account settings][] page... this is also explained in [the Semaphore API documentation][authentication].
-Next, choose one of the following mechanisms to make your API `authentication token` available to `Git::Semaphore`...
+Next, choose one of the following mechanisms to make your API authentication token available to `git semaphore`...
+### via *local* git config _(in a git working dir)_
+
+ git config --local --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+
+### via *global* git config
+
+ git config --global --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+
### via an environment variable
- $ export SEMAPHORE_AUTH_TOKEN="Yds3w6o26FLfJTnVK2y9"
+ export SEMAPHORE_AUTH_TOKEN="Yds3w6o26FLfJTnVK2y9"
-### via `local` git config _(in a git working dir)_
+This is also the order in which tokens are searched for - and hence their precedence - meaning that if you have different Semaphore accounts for different projects _(e.g. work and personal projects)_ then you can configure your respective git repos with the authentication token of the corresponding Semaphore account.
- $ git config --local --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+## API result caching
-### via `global` git config
+For performance reasons _(especially for Semaphore API calls that are paginated)_, to enable offline use of the Semaphore API data, as well as to support interactive use of the data in e.g. `irb` or `pry` sessions, `git semaphore` transparently caches the results of all API calls in the `${HOME}/.git/semaphore/` directory.
- $ git config --global --replace-all semaphore.authtoken "Yds3w6o26FLfJTnVK2y9"
+This means that running `git semaphore` commands may return stale data, in cases where things have changed on `semaphoreci.com` since the last time `git semaphore` was run.
-## Usage
+To delete the cache - and force a refresh of the Semaphore data on the next API call - use the `git semaphore --clean` command... this will empty out the entire `${HOME}/.git/semaphore` cache directory.
-All of the below examples need to be run from within a git directory.
+## Integration with `git`
-### listing of user's projects
+When used inside a git repository, `git semaphore` uses [convention over configuration][coc] to figure out the relevant settings it needs in order to make valid Semaphore API requests:
- $ git semaphore --projects
+| setting | inside git repo | pseudo-code | override |
+|--------------|--------------------|---------------------------------|---------------------------------|
+| project name | derived from pwd | `File.basename(Dir.pwd)` | `ENV['SEMAPHORE_PROJECT_NAME']` |
+| branch name | current git branch | `git symbolic-ref --short HEAD` | `ENV['SEMAPHORE_BRANCH_NAME']` |
+| commit SHA | current git head | `git rev-parse HEAD` | `ENV['SEMAPHORE_COMMIT_SHA']` |
-### listing of project's branches
+However, each of these defaults can be overridden by setting the corresponding environment variable, as documented in the above table. The same `ENV`-based override mechanism can be leveraged to use `git semaphore` outside of a git repository.
- $ git semaphore --branches
+The `git semaphore --settings` command can be used to print out the values for these various settings:
+ $ git semaphore --settings | jq '.'
+ {
+ "semaphore_auth_token": "Yds3w6o26FLfJTnVK2y9",
+ "semaphore_project_name": "git-semaphore",
+ "semaphore_branch_name": "master",
+ "semaphore_commit_sha": "4b59c3e41ca4592dfb01f77f2163154f3d3532fe"
+ }
+ $ _
+
+## Available commands
+
+> ⚠️ all of the below examples need to be run from within a git repository ⚠️
+
+### list the Semaphore settings
+
+ git semaphore --settings
+
+_(lists things like project name, branch name, commit SHA, etc.)_
+
+### open the Semaphore page for the project's current branch
+
+ git semaphore --browse
+
+_(the project and branch names are derived from the current git repository and the current git head)_
+
+### delete the local Semapore API cache
+
+ git semaphore --clean
+
+ _(this ensures the Semaphore data is refreshed for the subsequent API calls)_
+
+### list all Semaphore projects
+
+ git semaphore --projects
+
+_(for the Semaphore user account corresponding to the authentication token)_
+
+### list all of the project's branches
+
+ git semaphore --branches
+
_(the project name is derived from the current git directory)_
-### status of a project's branch
+### build status of the project's current branch
- $ git semaphore --status
+ git semaphore --status
-_(the project and branch name are derived from the current git directory and the current git head)_
+_(the project and branch names are derived from the current git repository and the current git head)_
-### formatting the raw `git semaphore` JSON output
+### build history of a project's branch
-After installing the quite brilliant [jazor gem][jazor] (`gem install jazor`), the `jazor` utility can be used to format the raw JSON output generated by the various `git semaphore` commands, as follows:
+ git semaphore --history
- $ git semaphore --projects | jazor -c
- $ git semaphore --branches | jazor -c
- $ git semaphore --status | jazor -c
+_(the project and branch names are derived from the current git repository and the current git head)_
+## Formatting the raw `git semaphore` JSON output
+
+After installing [the indispensable jq utility][jq] (`brew install jq`), the raw JSON output generated by the various `git semaphore` commands can be formatted and queried as follows:
+
+ # pretty-print the git semaphore settings
+ git semaphore --settings | jq '.'
+
+ # list the full name of all Semaphore projects
+ git semaphore --projects | jq -r '.[] | .full_name'
+
+ # get the status of the last build for the current branch
+ git semaphore --status | jq -r '.result'
+
+ # list the build duration (in minutes) for all "passed" builds of the current branch
+ git semaphore --history | jq -r '.builds | .[] | select(.result == "passed") | (.build_number|tostring) + "\t" + (.duration.minutes|tostring)'
+
+[semaphoreci.com]: https://semaphoreci.com/
+[account settings]: https://semaphoreci.com/users/edit
+[Semaphore API]: https://semaphoreci.com/docs/api.html
+
+[jq]: https://stedolan.github.io/jq/
+[coc]: https://en.wikipedia.org/wiki/Convention_over_configuration
+
## Development
- $ gem build git-semaphore.gemspec
- $ # this will generate a 'git-semaphore-x.y.z.gem' file
- $ gem install git-semaphore-x.y.z.gem
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
## Contributing
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
+Bug reports and pull requests are welcome on GitHub at https://github.com/pvdb/git-semaphore. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-[semaphoreci.com]: https://semaphoreci.com/
-[jazor]: https://github.com/mconigliaro/jazor
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+