README.md in git-semaphore-1.2.0 vs README.md in git-semaphore-2.0.0
- old
+ new
@@ -2,11 +2,11 @@
[](https://semaphoreci.com/pvdb/git-semaphore)
[](https://travis-ci.org/pvdb/git-semaphore)
-Integrate git repositories with their corresponding project on [semaphoreci.com][] _(via the semaphore API)_
+Integrate git repositories with their corresponding project on [semaphoreci.com][] _(via the Semaphore API)_
## Features
* highly opiniated
* integrated with `git`
@@ -106,31 +106,66 @@
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:
| setting | inside git repo | pseudo-code | override |
|--------------|--------------------|---------------------------------|---------------------------------|
-| project name | derived from pwd | `File.basename(Dir.pwd)` | `ENV['SEMAPHORE_PROJECT_NAME']` |
+| owner & name | based on `${PWD}` | `Dir.pwd.split('/').last(2)` | `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']` |
| build number | last branch build | `N/A` | `ENV['SEMAPHORE_BUILD_NUMBER']` |
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.
-The `git semaphore --settings` command can be used to print out the values for these various settings:
+## Using the "full name" convention
+On your local filesystem, git repositories need to use paths that follow the "full name" convention in use on `github.com` and `semaphoreci.com`, ie. the last two path components for the `pvdb/git-semaphore` repository should be `pvdb` and `git-semaphore` respectively, as illustrated on this table:
+
+| | full name | owner | name | URL / path |
+|-----------|----------------------|--------|-----------------|----------------------------------------------|
+| | `pvdb/git-semaphore` | `pvdb` | `git-semaphore` | |
+| GitHub | | | | `https://github.com/pvdb/git-semaphore` |
+| Semaphore | | | | `https://semaphoreci.com/pvdb/git-semaphore` |
+| filesytem | | | | `${HOME}/Projects/pvdb/git-semaphore` |
+
+Put differently: if you typically create your git repositories in `${HOME}/Projects`, and you have the following three git repos...
+
+ pvdb/git-meta
+ pvdb/git-semaphore
+ pvdb/git-switcher
+
+... then the directory tree should be as follows:
+
+ ${HOME}/Projects
+ └── pvdb
+ ├── git-meta
+ │ └── .git
+ ├── git-semaphore
+ │ └── .git
+ └── git-switcher
+ └── .git
+
+So first you have a directory corresponding to the repository owner (`pvdb`) and one level down you have a directory corresponding to the repository name (`git-meta`, `git-semaphore` and `git-switcher` respectively).
+
+## A look behind the scences
+
+The `git semaphore --settings` command can be used to print out the values for the most relevant settings:
+
$ git semaphore --settings | jq '.'
{
- "semaphore_auth_token": "Yds3w6o26FLfJTnVK2y9",
- "semaphore_project_name": "git-semaphore",
- "semaphore_branch_name": "master",
- "semaphore_commit_sha": "4b59c3e41ca4592dfb01f77f2163154f3d3532fe"
+ "auth_token": "Yds3w6o26FLfJTnVK2y9",
+ "project_name": "pvdb/git-semaphore",
+ "branch_name": "master",
+ "commit_sha": "4b59c3e41ca4592dfb01f77f2163154f3d3532fe",
+ "build_number": "35"
}
$ _
+The `git semaphore --internals` command adds all internal settings to the above settings hash.
+
## Available commands
-> ⚠️ all of the below examples need to be run from within a git repository ⚠️
+> ⚠️ all of the below examples need to be run from within a git repository that follows the "full name" convention documented above ⚠️
### list the Semaphore settings
git semaphore --settings
@@ -186,9 +221,12 @@
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 '.'
+
+ # pretty-print the git semaphore internals
+ git semaphore --internals | 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