Skip to content

Git Actions

Git actions provide version control operations for extracting files from Git history and cloning repositories.

Configuration

[[actions]]
name = "action-name"
type = "git"
command = "extract"  # or "clone"
# Command-specific fields below

Commands

extract

Extract a specific file from Git commit history. Useful for retrieving old versions of files from before certain changes were made.

Required Fields:

  • source (pathlib.Path): Path to the file in the repository
  • destination (ResourceUrl): Where to write the extracted file

Optional Fields:

  • commit_keyword (string): Keyword to search for in commit messages. If not provided, extracts from current HEAD (default: None)
  • search_strategy (string): How to find the commit - before_first_match or before_last_match. Only used when commit_keyword is provided (default: before_last_match)
  • ignore_errors (bool): Continue if extraction fails instead of raising RuntimeError (default: false)

Example: 

[[actions]]
name = "extract-old-config"
type = "git"
command = "extract"
source = "config.yaml"
destination = "extracted:///old-config.yaml"
commit_keyword = "update config"
search_strategy = "before_last_match"

Search Strategies:

  • before_first_match: Extract file from commit before the first match of keyword
  • before_last_match (default): Extract file from commit before the last match of keyword

clone

Clone a Git repository to a specific location.

Required Fields:

  • url (string): Git repository URL to clone
  • destination (ResourceUrl): Where to clone the repository

Optional Fields:

  • branch (string): Specific branch to clone
  • depth (int): Shallow clone depth (for faster clones)

Example: 

[[actions]]
name = "clone-external-repo"
type = "git"
command = "clone"
url = "https://github.com/example/repo.git"
destination = "extracted:///external-repo/"
branch = "main"
depth = 1

Common Use Cases

Extract File Before Breaking Change

[[actions]]
name = "get-old-dockerfile"
type = "git"
command = "extract"
source = "Dockerfile"
destination = "extracted:///Dockerfile.old"
commit_keyword = "breaking"
search_strategy = "before_last_match"
ignore_errors = true

Extract Config from Before Migration

[[actions]]
name = "backup-old-config"
type = "git"
command = "extract"
source = "config/settings.yaml"
destination = "extracted:///settings.yaml.backup"
commit_keyword = "migrate to new config"
search_strategy = "before_first_match"

[[actions]]
name = "merge-configs"
type = "shell"
command = "python scripts/merge-configs.py"
working_directory = "{{ working_directory }}"

Clone Template Repository

[[actions]]
name = "clone-template"
type = "git"
command = "clone"
url = "https://github.com/myorg/project-template.git"
destination = "extracted:///template/"
branch = "main"
depth = 1

[[actions]]
name = "copy-template-files"
type = "file"
command = "copy"
source = "extracted:///template/configs/*.yaml"
destination = "repository:///configs/"

Extract Multiple Historical Files

[[actions]]
name = "extract-old-requirements"
type = "git"
command = "extract"
source = "requirements.txt"
destination = "extracted:///requirements.old.txt"
commit_keyword = "update dependencies"
search_strategy = "before_last_match"

[[actions]]
name = "extract-old-dockerfile"
type = "git"
command = "extract"
source = "Dockerfile"
destination = "extracted:///Dockerfile.old"
commit_keyword = "update base image"
search_strategy = "before_last_match"

[[actions]]
name = "compare-versions"
type = "shell"
command = "diff -u extracted/requirements.old.txt repository/requirements.txt || true"
working_directory = "{{ working_directory }}"

Integration with Other Actions

Git Extract + File Copy Pattern

# Extract old version from git history
[[actions]]
name = "get-legacy-config"
type = "git"
command = "extract"
source = ".github/workflows/ci.yml"
destination = "extracted:///ci.yml.legacy"
commit_keyword = "migrate to v2"
search_strategy = "before_first_match"

# Copy to repository for comparison
[[actions]]
name = "save-for-reference"
type = "file"
command = "copy"
source = "extracted:///ci.yml.legacy"
destination = "repository:///.github/workflows/ci.yml.legacy"

Git Clone + Template Pattern

# Clone shared configuration repo
[[actions]]
name = "clone-shared-configs"
type = "git"
command = "clone"
url = "https://github.com/myorg/shared-configs.git"
destination = "extracted:///shared/"
branch = "main"

# Render templates from cloned repo
[[actions]]
name = "render-config"
type = "template"
source_path = "extracted:///shared/templates/"
destination_path = "repository:///config/"

Implementation Notes

Extract command:

  • If commit_keyword provided: Searches git log for commits matching keyword and extracts from the commit before the match
  • If no commit_keyword: Extracts file from current HEAD
  • Uses git show COMMIT:PATH to retrieve file contents
  • Returns false if file or commit not found (unless ignore_errors is true)
  • Works within the cloned repository directory ({working_directory}/repository/)
  • File must exist at the target commit (raises RuntimeError if not found)

Clone command:

  • Uses git clone with optional branch and depth parameters
  • Shallow clones (depth=1) are faster for large repositories
  • Cloned repository placed at destination path
  • Full git history available unless depth is specified

Search strategies:

  • before_first_match: Useful for finding original version before any changes
  • before_last_match: Useful for finding most recent version before latest change

Path resolution:

  • source paths are relative to repository root
  • destination supports all ResourceUrl schemes (extracted:///, repository:///, etc.)
  • Destination directories created automatically if needed