Merge pull request #281 from davidB/pr-git-describe

README.md

@@ -2,18 +2,17 @@
 
 Tracks the commits in a [git](http://git-scm.com/) repository.
 
-
 ## Source Configuration
 
 * `uri`: *Required.* The location of the repository.
 
 * `branch`: The branch to track. This is *optional* if the resource is
    only used in `get` steps; however, it is *required* when used in a `put` step. If unset for `get`, the repository's default branch is used; usually `master` but [could be different](https://help.github.com/articles/setting-the-default-branch/).
 
-
 * `private_key`: *Optional.* Private key to use when pulling/pushing.
     Example:
-    ```
+
+    ```yaml
     private_key: |
       -----BEGIN RSA PRIVATE KEY-----
       MIIEowIBAAKCAQEAtCS10/f7W7lkQaSgD/mVeaSOvSF9ql4hf/zfMwfVGgHWjj+W
@@ -57,13 +56,15 @@ Tracks the commits in a [git](http://git-scm.com/) repository.
 
 * `submodule_credentials`: *Optional.* List of credentials for HTTP(s) auth when pulling/pushing private git submodules which are not stored in the same git server as the container repository.
     Example:
+
     ```
     submodule_credentials:
     - host: github.com
       username: git-user
       password: git-password
     - <another-configuration>
     ```
+
     Note that `host` is specified with no protocol extensions.
 
 * `git_config`: *Optional.* If specified as (list of pairs `name` and `value`)
@@ -88,18 +89,17 @@ Tracks the commits in a [git](http://git-scm.com/) repository.
 * `gpg_keyserver`: *Optional.* GPG keyserver to download the public keys from.
   Defaults to `hkp:///keys.gnupg.net/`.
 
-
 * `git_crypt_key`: *Optional.* Base64 encoded
   [git-crypt](https://github.com/AGWA/git-crypt) key. Setting this will
   unlock / decrypt the repository with `git-crypt`. To get the key simply
   execute `git-crypt export-key -- - | base64` in an encrypted repository.
 
 * `https_tunnel`: *Optional.* Information about an HTTPS proxy that will be used to tunnel SSH-based git commands over.
   Has the following sub-properties:
-    * `proxy_host`: *Required.* The host name or IP of the proxy server
-    * `proxy_port`: *Required.* The proxy server's listening port
-    * `proxy_user`: *Optional.* If the proxy requires authentication, use this username
-  *   `proxy_password`: *Optional.* If the proxy requires authenticate,
+  * `proxy_host`: *Required.* The host name or IP of the proxy server
+  * `proxy_port`: *Required.* The proxy server's listening port
+  * `proxy_user`: *Optional.* If the proxy requires authentication, use this username
+  * `proxy_password`: *Optional.* If the proxy requires authenticate,
       use this password
 
 * `commit_filter`: *Optional.* Object containing commit message filters
@@ -189,7 +189,7 @@ resources:
 
 ## Behavior
 
-### `check`: Check for new commits.
+### `check`: Check for new commits
 
 The repository is cloned (or pulled if already present), and any commits
 from the given version on are returned. If no version is given, the ref
@@ -198,7 +198,7 @@ for `HEAD` is returned.
 Any commits that contain the string `[ci skip]` will be ignored. This
 allows you to commit to your repository without triggering a new version.
 
-### `in`: Clone the repository, at the given ref.
+### `in`: Clone the repository, at the given ref
 
 Clones the repository to the destination, and locks it down to a given ref.
 It will return the same given ref as version.
@@ -237,6 +237,8 @@ correct key is provided set in `git_crypt_key`.
 
 * `short_ref_format`: *Optional.* When populating `.git/short_ref` use this `printf` format. Defaults to `%s`.
 
+* `describe_ref_options`: *Optional.* When populating `.git/describe_ref` use this options to call [`git describe`](https://git-scm.com/docs/git-describe). Defaults to `--always --dirty --broken`.
+
 #### GPG signature verification
 
 If `commit_verification_keys` or `commit_verification_key_ids` is specified in
@@ -246,20 +248,24 @@ the case.
 
 #### Additional files populated
 
- * `.git/committer`: For committer notification on failed builds.
-   This special file `.git/committer` which is populated with the email address
-   of the author of the last commit. This can be used together with  an email
-   resource like [mdomke/concourse-email-resource](https://github.com/mdomke/concourse-email-resource)
-   to notify the committer in an on_failure step.
+* `.git/committer`: For committer notification on failed builds.
+ This special file `.git/committer` which is populated with the email address
+ of the author of the last commit. This can be used together with  an email
+ resource like [mdomke/concourse-email-resource](https://github.com/mdomke/concourse-email-resource)
+ to notify the committer in an on_failure step.
 
- * `.git/ref`: Version reference detected and checked out. It will usually contain
-   the commit SHA-1 ref, but also the detected tag name when using `tag_filter`.
+* `.git/ref`: Version reference detected and checked out. It will usually contain
+ the commit SHA-1 ref, but also the detected tag name when using `tag_filter`.
 
- *  `.git/short_ref`: Short (first seven characters) of the `.git/ref`. Can be templated with `short_ref_format` parameter.
+* `.git/short_ref`: Short (first seven characters) of the `.git/ref`. Can be templated with `short_ref_format` parameter.
 
- * `.git/commit_message`: For publishing the Git commit message on successful builds.
+* `.git/commit_message`: For publishing the Git commit message on successful builds.
 
-### `out`: Push to a repository.
+* `.git/describe_ref`: Version reference detected and checked out. Can be templated with `describe_ref_options` parameter.
+ By default, it will contain the `<latest annoted git tag>-<the number of commit since the tag>-g<short_ref>` (eg. `v1.6.2-1-g13dfd7b`).
+ If the repo was never tagged before, this falls back to a short commit SHA-1 ref.
+
+### `out`: Push to a repository
 
 Push the checked-out reference to the source's URI and branch. All tags are
 also pushed to the source. If a fast-forward for the branch is not possible
@@ -329,6 +335,7 @@ docker build -t git-resource -f dockerfiles/ubuntu/Dockerfile .
 If you want to run the integration tests, a bit more work is required. You will require
 an actual git repo to which you can push and pull, configured for SSH access. To do this,
 add two files to `integration-tests/ssh` (note that names **are** important):
+
 * `test_key`: This is the private key used to authenticate against your repo.
 * `test_repo`: This file contains one line of the form `test_repo_url[#test_branch]`.
   If the branch is not specified, it defaults to `master`. For example,

assets/in

@@ -50,6 +50,7 @@ gpg_keyserver=$(jq -r '.source.gpg_keyserver // "hkp://ipv4.pool.sks-keyservers.
 disable_git_lfs=$(jq -r '(.params.disable_git_lfs // false)' < $payload)
 clean_tags=$(jq -r '(.params.clean_tags // false)' < $payload)
 short_ref_format=$(jq -r '(.params.short_ref_format // "%s")' < $payload)
+describe_ref_options=$(jq -r '(.params.describe_ref_options // "--always --dirty --broken")' < $payload)
 
 # If params not defined, get it from source
 if [ -z "$fetch_tags" ] || [ "$fetch_tags" == "null" ]  ; then
@@ -196,6 +197,10 @@ echo "${return_ref}" | cut -c1-7 | awk "{ printf \"${short_ref_format}\", \$1 }"
 # for example
 git log -1 --format=format:%B > .git/commit_message
 
+# Store describe_ref when available. Useful to build Docker images with
+# a custom tag, or package to publish
+echo "$(git describe ${describe_ref_options})" > .git/describe_ref
+
 metadata=$(git_metadata)
 
 if [ "$clean_tags" == "true" ]; then

test/get.sh

@@ -696,6 +696,11 @@ it_can_get_returned_ref() {
   local expected_short_ref="test-$(echo ${ref3} | cut -c1-7)"
   test "$(cat $dest/.git/short_ref)" = $expected_short_ref || \
     ( echo ".git/short_ref does not match. Expected '${expected_short_ref}', got '$(cat $dest/.git/short_ref)'"; return 1 )
+
+  test -e $dest/.git/describe_ref || ( echo ".git/describe_ref does not exist."; return 1 )
+  local expected_describe_ref="0.9-production"
+  test "$(cat $dest/.git/describe_ref)" = $expected_describe_ref || \
+    ( echo ".git/describe_ref does not match. Expected '${expected_describe_ref}', got '$(cat $dest/.git/describe_ref)'"; return 1 )
 }
 
 it_can_get_commit_message() {