more advanced config options for git checkout

Author: ndbroadbent

README.md

@@ -13,6 +13,7 @@ The tool can generate both static CircleCI configs and setup/dynamic configs. Th
 - Package installation step generation and job deduplication
 - Basic automatic cache step injection when `job.cache` is declared
 - Architecture variants per job (e.g., `build_amd64`, `build_arm64`)
+- Advanced git checkout: shallow clone by default with configurable clone/fetch options, host key scanning, and path overrides
 - Descriptive error messages and schema/data validation ([miette], JSON Schema)
 
 ## Not Yet Implemented / In Progress

docs/astro.config.mjs

@@ -52,6 +52,7 @@ export default defineConfig({
           label: 'Configuration',
           items: [
             { label: 'Overview', slug: 'configuration/overview' },
+            { label: 'Checkout', slug: 'configuration/checkout' },
             { label: 'Cache System', slug: 'configuration/cache' },
             { label: 'Package Management', slug: 'configuration/packages' },
           ],

docs/src/content/docs/configuration/cache.mdx

@@ -111,7 +111,6 @@ cache:
     image: cimg/ruby:3.3
     cache: gems  # Uses all defaults from gems cache definition
     steps:
-      - checkout
       - run: bundle install
       - run: bundle exec rspec`}
   lang="yaml"
@@ -129,7 +128,6 @@ This injects a `restore_cache` step before, and a `save_cache` step after, when
     cache: [gems, node_modules]  # Multiple cache types
     services: [postgres]
     steps:
-      - checkout
       - run: bundle install
       - run: npm install
       - run: bundle exec rspec`}
@@ -148,7 +146,6 @@ This injects a `restore_cache` step before, and a `save_cache` step after, when
         paths: [vendor/rubygems, .bundle]  # Override paths
         # versions and checksum_sources from definition
     steps:
-      - checkout
       - run: bundle install --path vendor/rubygems`}
   lang="yaml"
   title="Customizing cache paths"

docs/src/content/docs/configuration/checkout.mdx

@@ -0,0 +1,102 @@
+---
+title: Checkout
+description: Advanced, configurable git checkout with shallow clone by default
+---
+
+import { Code, Aside, Steps, CardGrid, Card } from '@astrojs/starlight/components';
+
+Cigen automatically inserts a checkout step at the start of every job. By default this is a fast, shallow checkout implemented by a built-in `shallow_checkout` command.
+
+## Configuration
+
+Checkout can be configured at multiple levels, with this precedence:
+
+- Job-level `checkout`
+- Workflow-level `checkout`
+- Global `checkout`
+- Defaults (shallow checkout)
+
+### Parameters
+
+- `shallow` (boolean, default: true): when false, use CircleCI’s standard `checkout` step
+- `clone_options` (string): options for the initial clone, e.g. `--depth 1 --verbose`
+- `fetch_options` (string): options for `git fetch`, e.g. `--depth 10`
+- `tag_fetch_options` (string): options for fetching tags (default: `--tags`)
+- `keyscan` (map): add SSH host keys (`github`, `gitlab`, `bitbucket` ⇒ boolean)
+- `path` (string): checkout directory
+
+### Disable Checkout
+
+Set `checkout: false` at the global, workflow, or job level to skip inserting any checkout step for those scopes.
+
+<Code code={`jobs:
+  lint:
+    image: cimg/node:20.11
+    checkout: false  # do not checkout repo for this job
+    steps:
+      - run: npm run lint`} lang="yaml" title="Disable checkout for a job" />
+
+### Global Example
+
+<Code code={`checkout:
+    shallow: true
+    clone_options: "--depth 1"
+    fetch_options: "--depth 10"
+    tag_fetch_options: "--tags"
+    keyscan:
+      github: true
+      gitlab: false
+      bitbucket: false
+    path: "."`} lang="yaml" title="Global checkout configuration" />
+
+### Job Override Example
+
+<Code code={`jobs:
+  build:
+    image: cimg/node:20.11
+    checkout:
+      shallow: true
+      fetch_options: "--depth 50 --no-tags"
+    steps:
+      - run: npm run build`} lang="yaml" title="Job-level checkout override" />
+
+<Aside type="note">
+  Do not add `checkout` or `shallow_checkout` in your job steps — cigen inserts the checkout step automatically.
+  Set `shallow: false` to emit CircleCI's standard `checkout` step (optionally with `path`).
+</Aside>
+
+## Generated Output
+
+<Code code={`steps:
+  - shallow_checkout
+  - run:
+      name: Build application
+      command: npm run build`} lang="yaml" title="Shallow checkout (default)" />
+
+<Code code={`steps:
+  - shallow_checkout:
+      fetch_options: --depth 50 --no-tags
+      keyscan_github: true
+      path: .`} lang="yaml" title="Parameterized shallow checkout" />
+
+<Code code={`steps:
+  - checkout
+  - run:
+      name: Build application
+      command: npm run build`} lang="yaml" title="Standard checkout (shallow: false)" />
+
+## Best Practices
+
+- Prefer shallow checkout for most jobs to reduce time and IO.
+- Increase `fetch_options` depth in jobs that need more history (e.g., changelog tooling).
+- Use `tag_fetch_options` when building from tags; disable tags (`--no-tags`) to reduce noise if unused.
+- Enable `keyscan` only for hosts you actually use (GitHub/GitLab/Bitbucket).
+- Use `path` when checking out into a subdirectory.
+
+## Migration
+
+If your configs include explicit `checkout` steps in job definitions:
+
+- Remove manual `checkout` steps; cigen now inserts checkout automatically.
+- If you required full history, set `checkout.shallow: false` at the appropriate scope.
+- If you used custom clone or fetch options, move them under the `checkout` section.

docs/src/content/docs/configuration/overview.mdx

@@ -54,10 +54,10 @@ POSTGRES_PASSWORD: test
 # Job definitions
 
 jobs:
-test:
-image: cimg/ruby:3.3
-services: [postgres]
-steps: - checkout - run: bundle exec rspec
+  test:
+    image: cimg/ruby:3.3
+    services: [postgres]
+    steps: [shallow_checkout, { run: bundle exec rspec }]
 
 # Workflow definitions
 
@@ -99,6 +99,10 @@ Cigen supports both single-file and multi-file configurations:
 
 ## Key Differences from Native CI Formats
 
+### Checkout Defaults
+
+By default, cigen performs a fast, shallow checkout via a built-in `shallow_checkout` command. You can override behavior globally or per job using the `checkout` section (see CircleCI provider docs for parameters). Set `shallow: false` to use the standard `checkout` step.
+
 ### Cleaner Step Syntax
 
 <Aside type="tip">