mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-07 03:15:56 +00:00
kevinveenbirkenbach
6726f36799
- 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
77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# 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](https://www.veen.world)
|
|
|
|
Part of the **Infinito.Nexus Project**
|
|
🔗 [https://s.infinito.nexus/code](https://s.infinito.nexus/code)
|