0 Fork 0

mirror of https://github.com/kevinveenbirkenbach/computer-playbook.git synced 2026-11-06 19:01:54 +00:00

Files

T

kevinveenbirkenbach 6726f36799 feat(sys-util-git-pull): introduce reusable shallow git pull role with tag pinning

- Add new role sys-util-git-pull as a generic system utility
- Implement robust shallow clone/update logic in Python helper
- Support detached-safe branch updates and optional tag pinning
- Handle annotated vs lightweight tags and heal local tag conflicts
- Provide deterministic Ansible change detection via machine-readable output
- Add verbose logging to stderr for debuggability
- Integrate sys-util-git-pull into pkgmgr role to replace inline git logic
- Add comprehensive unit tests (option A: file-based import) for helper script
- Add role README and meta information with platform-agnostic support
- Ensure role conforms to existing test expectations (meta/main.yml present)

https://chatgpt.com/share/69481902-a98c-800f-9b3f-9ee13e8e50b7

2025-12-21 16:57:45 +01:00

2.3 KiB

Raw Blame History

System Utility: Git Pull (Shallow & Pinned) 🔧📥

Description

This Ansible role provides a robust, reusable Git pull utility for system automation. It performs shallow clones or updates of Git repositories and optionally pins the working tree to a specific tag (e.g. stable) in a detached HEAD state.

The role is designed to solve common automation pitfalls such as:

conflicting local tags (would clobber existing tag)
detached HEAD updates
annotated vs. lightweight tags
reliable change detection for Ansible

Internally, the role delegates complex Git logic to a small, well-tested Python helper script, keeping the Ansible YAML concise and readable.

Overview

This role:

Ensures a repository exists at a given destination
Clones the repository shallowly if it does not exist
Updates an existing repository in a detached-safe manner
Optionally removes conflicting local tags before fetching
Optionally pins the checkout to a specific tag (e.g. stable)
Marks the Ansible task as changed if:
- the repository was cloned
- tags were removed
- the pinned tag appeared for the first time
- the pinned tag moved on the remote (optional)

Purpose

The purpose of this role is to provide a generic, reusable Git pull primitive for other roles in the Infinito.Nexus ecosystem.

Typical use cases include:

installing tools pinned to a stable tag
reproducible system deployments
CI/CD-friendly shallow clones
avoiding fragile inline Git shell logic in roles

Features

Shallow Clone & Update (--depth)
Detached-safe Branch Updates
Optional Tag Pinning (e.g. stable)
Annotated Tag Support (tag^{})
Local Tag Conflict Healing
Deterministic changed_when Semantics
Verbose Debug Logging (stderr-only)

Design Notes

All human-readable logs go to stderr
Machine-readable state (CHANGED=…) is written to stdout
This guarantees reliable changed_when behavior in Ansible
The Python helper is intentionally self-contained and unit-testable

Credits 📝

Developed and maintained by Kevin Veen-Birkenbach Learn more at www.veen.world

Part of the Infinito.Nexus Project 🔗 https://s.infinito.nexus/code

2.3 KiB Raw Blame History