> For the complete CircleCI developer hub index, see [llms.txt](https://circleci.com/developer/llms.txt)

# guitarrapc/git-shallow-clone

Provides git shallow clone instead of full clone. Supporting trigger for tag, pull_request and push, works on Alpine, Debian, Ubuntu, and macOS.
What's shallow clone? - see https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt Provied commands: - checkout - checkout_advanced
requirement: git


## Commands

### checkout

Provides git shallow clone instead of full clone. This command is for simple usage when you don't need options for clone, fetch and tag fetch.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `depth` | integer | 1 | Limit fetch depth to the specified number of commit from a remote branch history. Refer git fetch documentation for more information.
 |
| `fetch_depth` | integer | 10 | Addtional fetch depth to the specified number of commit from a remote branch history. Pass more number then depth when you want to check futher commit history.
 |
| `keyscan_bitbucket` | boolean | false | Pass `true` to dynamically get ssh-rsa from `bitbucket.org`.
 |
| `keyscan_github` | boolean | false | Pass `true` to dynamically get ssh-rsa from `github.com`.
 |
| `no_tags` | boolean | false | true to add '--no-tags' when fetching. As git not offer tag depth, we only able to control fetch all tags or not. This enable you to stop fetch tags when you have vast numbers of tags during specified fetch depth. In other word, if you need tag then fetch specified tags manually when use 'without_tag: true'.
 |
| `path` | string | . | Checkout directory (default: job working_directory)
 |

### checkout_advanced

Provides git shallow clone instead of full clone. This command is for advaned usage when you need options for clone, fetch and tag fetch.


| Parameter | Type | Default | Description |
|---|---|---|---|
| `clone_options` | string | --depth 1 | git clone options you want to add such as '--depth 1 --verbose' and '--depth 1 --shallow-since "5 days ago"'
 |
| `fetch_options` | string | --depth 10 | git fetch options you want to add such as '--depth 1 --verbose' and '--depth 1 --shallow-since "5 days ago"' you don't need set '--force' option as it already set by default. in case of tag, add '--no-tags' on this option and tag_fetch_options.
 |
| `keyscan_bitbucket` | boolean | false | Pass `true` to dynamically get ssh-rsa from `bitbucket.org`.
 |
| `keyscan_github` | boolean | false | Pass `true` to dynamically get ssh-rsa from `github.com`.
 |
| `path` | string | . | Checkout directory (default: job working_directory)
 |
| `tag_fetch_options` | string | --tags | This option apply when git operation is tag. Use 'fetch_options' instead if pr and other git operation. Additional git fetch options you want to add specifically for tags such as '--tags' or '--no-tags'. Default value is '--tags'
 |

## Examples

### checkout

Simple git shallow clone instead of checkout.
You can change depth and fetch_depth, but I do recommend set fetch_depth larger than 1.
If you set fetch_depth 1, you will find build failed when new commit was pushed.
Default value of `fetch_depth` is 10 to cover re-build after several commit.

# No options will clone depth 1 and fetch depth 10.
- git-shallow-clone/checkout
# Clone the repository to specific path `src`.
- git-shallow-clone/checkout:
    path: src
# Set fetch_depth: 1 to minimize fetch time.
- git-shallow-clone/checkout:
    fetch_depth: 1
# Change depth:5 for some reason.
- git-shallow-clone/checkout:
    depth: 5
    fetch_depth: 5
# Enable ssh key scan for github.com and bitbucket.org. Omit this parameter use embedded known ssh key by default.
- git-shallow-clone/checkout:
    keyscan_github: true
    keyscan_bitbucket: true
# Skip tag fetch.
- git-shallow-clone/checkout:
    no_tags: true
# Shallow clone then update submodules.
- git-shallow-clone/checkout
- run: git submodule update --init --recursive


```yaml
version: '2.1'
orbs:
  git-shallow-clone: guitarrapc/git-shallow-clone@x.y.z
workflows:
  build:
    jobs:
      - git-shallow-clone/checkout
```

### checkout_advanced

Advanced git shallow clone instead of checkout with clone_options and fetch_options.
Make sure some options is exclusive each other, you should follow to official git documentation.
e.g. `--depth N` cannot use with `--shallow-since`.

# No options will clone depth 1 and fetch depth 10.
- git-shallow-clone/checkout_advanced
# Clone the repository to specific path `src`.
- git-shallow-clone/checkout_advanced
    path: src
# See verbose log on clone.
- git-shallow-clone/checkout_advanced
    clone_options: '--depth 1 --verbose'.
# Use --shallow-since for clone timing, but not for fetch timing.
- git-shallow-clone/checkout_advanced
    clone_options: '--shallow-since "5 days ago"'
# Use --shallow-since for fetch timing, but not for clone timing.
- git-shallow-clone/checkout_advanced
    fetch_options: '--shallow-since "5 days ago"'
# Use --no-tags to skip tag fetch.
- git-shallow-clone/checkout_advanced
    fetch_options: '--depth 10 --no-tags'
# Skip tag fetch.
- git-shallow-clone/checkout_advanced
    fetch_options: '--depth 10 --no-tags'
    tag_fetch_options: '--no-tags'
# Shallow clone then update submodules.
- git-shallow-clone/checkout_advanced
- run: git submodule update --init --recursive


```yaml
version: '2.1'
orbs:
  git-shallow-clone: guitarrapc/git-shallow-clone@x.y.z
workflows:
  build:
    jobs:
      - git-shallow-clone/checkout_advanced:
          clone_options: '--shallow-since "5 days ago"'
          fetch_options: '--shallow-since "5 days ago"'
```