step.yml

title: "Bitrise.io Cache:Push"
summary: "Updates the Cache, if required"
description: |-
  Checks whether cache has to be updated based on the **Cache Paths** and **Ignore Paths** inputs.
  If it does, the Step creates a new cache archive and uploads it. 
  It won't update/upload the cache if the cache hasn't changed nor in the case of a pull request unless you change the Step's `run_if` property. 
  For caching, you will need the **Bitrise.io Cache:Pull** Step at the beginning of your Workflow (after the **Git Clone Repository** Step but before a dependency installer Step) to download the previous cache, if any. 
  The **Bitrise.io Cache:Push** Step should be the very last Step in your Workflow.
  
  ### Configuring the Step

  1. Cache any directory or file by adding it in the **Cache paths** field.
  For most cases, caching will automatically work based on your native build and testing Steps as these automatically configure cache paths in your cache Steps.
  If adding multiple paths, separate them with a newline.
  If you have a path in the list which does not exist, it will not cause the Step to fail. 
  You can also specify an update indicator file with the `->` syntax, for example, `update/this -> if/this/file/is/updated.` 
  Please note the indicator points to a file and not to a folder.
  2. In the **Ignore Paths from change check** field, you can set any path which you don't want to do change analysis for.
  - Paths prefixed with an `!` will get ignored from the cache archive.
  - The path can also include `*`, `**`, `/`. 
  The `*` will replace a path element, the `**` will replace part of a path. 
  To exclude a full directory, simply put a `/` behind the directory.
  Note that you can't ignore a path which results in an invalid cache item.
  3. Modify **Working directory** if you wish to set relative cache paths and reference them from a working directory other than `$BITRISE_SOURCE_DIR`.
  4. Select a **Fingerprint Method** option (`file-content-hash` or `file-mod-time`) to detect changes in a directory, file, or in an update indicator file. 
  If changes are detected, new cache gets generated.
  5. If you set **Debug mode?** input to `true`, the Step will print out more detailed logs.
  6. With **Compress cache?** input set to `true`, you can compress the cache archive for faster uploads and downloads, especially useful for node-modules and other huge dependency folders.
  7. In `Ignore paths collected by steps` you can set which files or extensions should be ignored by the Step during the build.
  8. `Cache Upload URL` shows the URL where the cache gets uploaded.
  
  ### Troubleshooting
  We recommend you do not cache any dependency manager lock file (for example, `package.lock`, `gemfile.lock`, `podfile.lock`) as it would override the lock file in your repository.

  ### Useful links
  - [About caching](https://devcenter.bitrise.io/builds/caching/about-caching-index/)
  - [Caching Cocoapods](https://devcenter.bitrise.io/builds/caching/caching-cocoapods/)
  - [Caching Gradle](https://devcenter.bitrise.io/builds/caching/caching-gradle/)

  ### Related Steps
  - [Bitrise.io Cache:Pull](https://www.bitrise.io/integrations/steps/cache-pull)
  - [Git Clone Repository](https://www.bitrise.io/integrations/steps/git-clone)
  
website: https://github.com/bitrise-steplib/steps-cache-push
source_code_url: https://github.com/bitrise-steplib/steps-cache-push.git
support_url: https://github.com/bitrise-steplib/steps-cache-push/issues
host_os_tags:
  - osx-10.10
  - ubuntu-14.04
project_type_tags: []
type_tags:
  - utility
toolkit:
  go:
    package_name: github.com/bitrise-steplib/steps-cache-push
is_requires_admin_user: false
is_always_run: false
is_skippable: true
deps:
  apt_get:
  - name: tar
run_if: ".IsCI | and (not .IsPR)"
inputs:
  - cache_paths: |
      $BITRISE_CACHE_DIR
    opts:
      title: "Cache paths"
      summary: Cache these paths. Separate paths with a newline.
      description: |-
        Cache these paths. Separate paths with a newline.

        A path item can be either a file or a directory.

        You can also specify an "update indicator file" with the `->`
        syntax: `update/this -> if/this/file/is/updated`.
        *The indicator can only be a file!*

        If you have a path in the list which doesn't exist that will not cause
        this step to fail. It'll be logged but the step will try to gather
        as many specified & valid paths as it can, and just print a warning
        about the invalid items.
  - ignore_check_on_paths:
    opts:
      title: "Ignore Paths from change check"
      summary: "Define the paths which have to be ignored when checking for cache changes."
      description: |-
        These paths will be ignored from change checking.
        If something has changed under the specified path(s) and nothing else has changed,
        then the cache won't be updated.

        **Paths prefixed with an `!` will get ignored from the cache archive**.
        If a path is located inside a specified Cache Path item and not prefixed with an `!`,
        it'll be included in the cache archive, but won't be checked for changes. 

        The path can also include `*`, `**`, `/`.
        `*` will replace a path element (for example, `a/*/b` will match `a/x/b`).
        `**` will replace part of a path (for example, `a/**/b` will match `a/x/y/z/b`).
        To exclude a full directory like `/my/full/path`, simply put a `/` behind `/my/full/path`,
        so it will be `/my/full/path/`.

        Important: you can't ignore a path which results in an invalid cache item.
        For example, if you specify the path `a/path/to/cache` to be cached, you
        can't ignore `a/path/to`, as that would ignore every file from checking
        for a change and no fingerprint could be generated for `a/path/to/cache`.
        You can ignore paths inside a Cache Path, however, if, for example, a path is `a/path/to/cache`, you can ignore `a/path/to/cache/.ignore-me`,
        unless that's the only file inside `a/path/to/cache`.

        The point is: you should not specify an ignore rule which would completely
        ignore a specified Cache Path item, as that would result in a path which
        can't be checked for updates,changes or fingerprints.
  - workdir: $BITRISE_SOURCE_DIR
    opts:
      title: Working directory path
      summary: Working directory path
      description: |-
        Working directory path - should be an absolute path.
  - fingerprint_method: "file-content-hash"
    opts:
      title: Fingerprint Method
      summary: Fingerprint method, used for checking file changes.
      description: |-
        The specified Fingerprint Method will be used to calculate
        fingerprints for the cached files.

        The (file) fingerprint is used to check whether
        the cached files did change - if it changed, a new cache will be generated.
        If the fingerprint matches the previous cache version's fingerprint, then
        no new cache will be generated.

        **Regardless of which method you choose** the following file attributes will
        be used to create the fingerprint **in addition** to the method you choose:

        * File path
        * File size
        * File permission bits

        Information about the options:

        * `file-content-hash` : create a file content checksum hash for every file in the cache,
          and use that as the fingerprint source of the file. This means that **the full file content will be loaded** in
          order to create the checksum hash!
        * `file-mod-time` : use the file's "modified at" time information. For larger files this method
          can be significantly faster, as the file doesn't have to be loaded to calculate this information!

        **Note**: in case of "update indicator files", the fingerprint method will always be `file-content-hash`,
        regardless of which option you select here.
      value_options:
      - file-content-hash
      - file-mod-time
  - is_debug_mode: "false"
    opts:
      title: "Debug mode?"
      summary: "If debug mode is enabled, the step will print verbose logs."
      description: |-
        If debug mode is enabled the step will print verbose logs.
      is_required: true
      value_options:
      - "true"
      - "false"
  - compress_archive: "false"
    opts:
      title: "Compress cache?"
      summary: "If Compress cache is set to `true`, then it will upload a compressed archive."
      description: |-
        If Compress cache is set to `true`, then it will upload a compressed archive.
      is_required: true
      value_options:
      - "true"
      - "false"
  - bitrise_cache_include_paths: $BITRISE_CACHE_INCLUDE_PATHS
    opts:
      title: "Cache paths collected by steps"
      summary: "Collected dependencies by steps from the build"
      is_required: true
      is_dont_change_value: true
  - bitrise_cache_exclude_paths: $BITRISE_CACHE_EXCLUDE_PATHS
    opts:
      title: "Ignore paths collected by steps"
      summary: "Changing files or extensions are collected regularly by steps from the build."
      is_required: true
      is_dont_change_value: true
  - cache_api_url: $BITRISE_CACHE_API_URL
    opts:
      title: "Cache Upload URL"
      summary: "Cache Upload URL"
      description: |-
        Cache Upload URL
      is_required: true
      is_dont_change_value: true