A tiszta kód első védelmi vonala előzetes elkötelezettség: hogyan kell beállítani

Valaha véletlenül nyomott titkokat egy tárolóba? Vagy talán nyomott formázatlan kódot, csak azért, hogy létre kell hoznia egy utólagos „csíkos” kompromisszumot? Mindannyian ott voltunk.Ezek a kis hibák sikertelen CI / CD csővezetékekhez és frusztráló késésekhez vezethetnek, mindezt a helyszínen végrehajtott ellenőrzések miatt.

A Git hooks egy erőteljes eszköz, amellyel megakadályozhatja ezeket a problémákat a szkriptek futtatásával, mielőtt elkötelezné magát vagy nyomja meg.

A Pre-commit egy könnyen használható keretrendszer a többnyelvű git hooks kezeléséhez és megosztásához, amely segít a problémák elkapásában, mielőtt elhagyják a munkaállomást.

Kezdőlap » A helyes beállítás

Mielőtt kihasználná a pre-commit erejét, telepítenie kell, és konfigurálnia kell a projektekhez.

telepítés

Többféle módja van a pre-commit telepítésének:

• MacOS és Linux:

brew install pre-commit

• Python / Pip (platformon átívelő)

pip install pre-commit

• Egyéb módszerek: A Conda vagy a Windows használatával történő telepítésekhez kérjük, olvassa el a Hivatalos Dokumentációt.

Projektspecifikus beállítás (Standard Way)

Ez a leggyakoribb megközelítés az előre elkötelezettség lehetővé tételére egy adott projektben:

1. Create a Configuration File: In the root of your repository, create a file named .pre-commit-config.yaml. This file will define the hooks pre-commit should run. (We’ll cover how to populate this file in the next section).

   
   

2. Install Hooks: Navigate to your repository’s root directory in your terminal and run:

pre-commit install

3. Ez a parancs telepíti a git hooks-ot a tárolóban lévő .git/hooks könyvtárba. Mostantól kezdve a pre-commit automatikusan elvégzi ellenőrzéseit, mielőtt minden egyes kompromisszumot elvégezne ebben a konkrét tárolóban.

Global Setup (A „Set It and Forget It” módszer)

Ha gyakran indít új projekteket vagy klónozza a tárhelyeket, és alapértelmezés szerint szeretné, hogy a pre-commit aktív legyen (ha létezik konfiguráció), akkor globálisan is beállíthatja.init.templateDirA funkció.

1. A Configuration File: All your repository must have a .pre-commit-config.yaml. This file will define the hooks that pre-commit should run. The best would be to use a template repository with a minimal pre-commit file.

   
   

2. Configure Git’s Template Directory: Tell Git to use a specific directory as a template for new repositories:

git config --global init.templateDir ~/.git-template

(Ha úgy tetszik, kiválaszthat egy másik könyvtárat, csak győződjön meg róla, hogy a következő lépésben következetes.)

3. A Pre-commit kezdeményezése a Template Directory-ban: Végezze el a következő parancsot:

pre-commit init-templatedir ~/.git-template

(Ha az előző lépésben egy másik könyvtárat választott, cserélje ki a~/.git-templateEnnek megfelelően )

Ez egy nagy előny: Ezzel a globális beállítással bármilyen új tárhelyet kezdeményez (git init) vagy egy klón automatikusan telepíti a pre-commit hook-ot..pre-commit-config.yamlA fájl, az előzetes kötelezettségvállalás egyszerűen nem fog semmit tenni, így biztonságos globálisan engedélyezni.

Mégis, szeretnék egy lépéssel tovább menni egy alapértelmezett horgolás hozzáadásával~/.git-template/hooks/pre-commitrendszeresen kudarcot vallana, ha a tároló nem rendelkezne.pre-commit-config.yamlÍme a hook tartalma.

#!/usr/bin/env bash
if [ -f .pre-commit-config.yaml ]; then
    echo 'pre-commit configuration detected, but `pre-commit install` was never run' 1>&2
    exit 1
fi

Konfiguráció létrehozása (.pre-commit-config.yaml)

A pre-commit szíve a.pre-commit-config.yamlEz a fájl, elhelyezve a gyökér a tároló, azt mondja, előzetes megbízás, amely ellenőrzi, hogy fut.

# https://github.com/xNok/infra-bootstrap-tools/blob/main/.pre-commit-config.yaml
repos:
  # Lint all yam files
  - repo: https://github.com/adrienverge/yamllint.git
    rev: v1.29.0
    hooks:
      - id: yamllint
  # Runs Ansible lint
  - repo: https://github.com/ansible/ansible-lint
    rev: v24.7.0
    hooks:
      - id: ansible-lint
        args:
          - "ansible"
        additional_dependencies:
          - ansible

Megmagyarázott alapvető szerkezet

Egy tipikus konfiguráció magában foglalja a tárolóhelyek listáját, amelyek mindegyike specifikus kapukkal rendelkezik:

• repos: Ez egy felső szintű kulcs, amely a tárhely-mappingok listáját foglalja magában. A lista minden elemének meg kell határoznia egy Git tárhelyet, amely pre-commit hooksokat tartalmaz.

• repo: A tárhely URL-je tárolja a kapukat (például https://github.com/pre-commit/pre-commit-hooks). Ez egy nagyon jó módja a függőségek kezelésének. Ha többet tud az eszközről, akkor a tárhelyre mehet.

• rev: Meghatározza a használni kívánt hooks verzióját, vagy egy Git tag, SHA vagy ághoz kapcsolva. De azt javasoljuk, hogy mindig használjon egy adott címkét vagy SHA-t (nem egy olyan ágot, mint a mester), hogy biztosítsa, hogy a kötése ne szakadjon meg váratlanul, amikor a távoli tár frissül.

• hooks: Minden egyes repo-bejegyzés alatt egy lista.Ebben az esetben minden egyes elem meghatároz egy adott hookot, amelyet az adott tárolóról kell használni.

• id: A kötél egyedi azonosítója (például trailing-whitespace, check-yaml). A rendelkezésre álló kötél azonosítókat megtalálhatja a kötél tároló dokumentációjában. vagy egyszerűen a .pre-commit-hooks.yaml a repo gyökerén.

Gyakorlati kezdő konfiguráció

Itt egy alapvető.pre-commit-config.yamlEz a példa, azt tanácsolom, hogy menjen a Github és egy pillantástpre-commit/pre-commit-hooks / blob/main / pre-commit-hooks / pre-commit-hooksEz a lista az egyszerű horgok, hogy apre-commita csapat már végrehajtott, és hol lehet megtalálni aidMindegyik, az Ön által használni kívánt szőnyeg.

Azt mondanámtrailing-whitespaceésend-of-file-fixerNagyon hasznos, így a konfiguráció így fog kinézni.

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.6.0  # Check for the latest stable version on the pre-commit-hooks repo!
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
# Add other repositories and their specific hooks below
# -   repo: ...
#     rev: ...
#     hooks:
#     -   id: ...

Megjegyzés: A horgok verziói idővel változnak. Jó gyakorlat, ha alkalmanként ellenőrizzük apre-commit-hookstároló (vagy bármely más, Ön által használt rögzítő tároló) a legújabb stabil verzió címkéhez, és frissítse arevVagy legyen automatizálva, mint például a Renovate vagy a Dependabot, hogy azokat rendszeresen frissítse.

Megtalálható egy nagy listát a már meglévő hooks aElőzetes weboldalA tapasztalatom szerint ez a lista messze nem kimerítő; ehelyett inkább ellenőriztem azokat az eszközöket, amelyeket szeretnék használni..pre-commit-hooks.yamlNézze meg, hogy vannak-e még hook-ok.

Jó tudni, mikor kell használni a Pre-Commit

Miután jól érezte magát az alapokat, a pre-commit fejlettebb funkciókat kínál a munkafolyamat finomításához.

Kézműves hajtás manuálisan

Miközben a hooks automatikusan futgit commitElőfordulhat, hogy más időpontokban manuálisan szeretné kiváltani őket:

• Specifikus csavar futtatása: Egyetlen csavar végrehajtásához (például konfigurációjának teszteléséhez vagy módosításainak alkalmazásához kötelezettségvállalás nélkül) használja:

pre-commit run <hook_id>

(Helyettesítő<hook_id>a tényleges azonosítóval a konfigurációs fájlból.)

• Az összes fájl futtatásához: Az összes konfigurált hook futtatásához minden nyomon követett fájl a raktárban (nem csak a lépcsőzetes változások), használja:

pre-commit run --all-files

Ez hasznos egy kezdeti takarításhoz, vagy ha új kapukat adunk hozzá egy meglévő projekthez.

Hozzon létre saját helyi hooks

Előfordulhat, hogy olyan projekt-specifikus szkripteket vagy ellenőrzéseket használ, amelyek nem tartoznak a nyilvános kötéltárba.Az előzetes megbízás lehetővé teszi „helyi” kötél meghatározását.

1. Írja le a forgatókönyvet: Hozza létre a forgatókönyvet (például egy shell forgatókönyvet, Python forgatókönyvet) a tárolóban.
2. Határozza meg a .pre-commit-config.yaml-ban: Hozzáad egy helyi ragasztóbejegyzést a konfigurációhoz:

# .pre-commit-config.yaml
-   repo: local
    hooks:
    -   id: my-custom-check
        name: My custom check
        entry: ./my_custom_script.sh # Path to your script
        language: script             # Or python, node, etc.
        files: \.(py)$               # Example: regex to run only on Python files
        # verbose: true              # Uncomment for more output
        # args: [--custom-arg]       # Optional arguments for your script

Ez azt jelenti, hogy a pre-commit futmy_custom_script.sha Pythonban bekövetkezett változások (.pyA fájlokat, alanguage: scriptA típus nagyon rugalmas; specifikus környezetekhez, mint például a Python vagy a Node, megadhatja azokat a függőségek kezelésére, ha szükséges.bashA hook.

Mégis, a pre-commit nagyon okos a munkakörnyezetek tekintetében, mivel elkülönített futási környezetet hoz létre az eszközök és a szükséges függőségek számára.

Sajnos nem minden kapocs használta ki a függőségi funkciót, és előfordulhat, hogy magának kell telepítenie az eszközöket, hogy képes legyen futtatni a kaput (például a terraformra gondolok).

Előzetes elkötelezettség egy csapatban és CI / CD környezetben

Míg a pre-commit ragyog az egyes fejlesztői gépeken, az előnyei megsokszorozódnak a csapatmunkafolyamatokba és a CI/CD csővezetékekbe integrálva. Még a helyi telepítésű pre-commit hooks esetén is valaki véletlenül hooks nélkül köthet (pl.git commit --no-verifyAz Ön CI/CD csővezetékének lehet a végső átjárója.

Azáltal, hogy elkötelezettség előtti ellenőrzéseket futtat a CI csővezetékben, biztosítja, hogy a projekt szabványait sértő kódok ne kerüljenek egyesítésre.

pre-commit run --all-files

Ez a parancs ellenőrzi az összes fájlt a tárban, nem csak a módosított fájlokat, biztosítva az átfogó érvényesítést.

Koncepcionális CI csővezeték lépés (például GitHub cselekvések):

# Example for a GitHub Actions workflow
# ... (other steps like checkout, setup python/node, etc.)
- name: Install pre-commit and dependencies
  run: |
    pip install pre-commit
    # Install any other dependencies your hooks might need (e.g., linters)
    # This might be minimal if your hooks install their own dependencies (common).
- name: Run pre-commit checks
  run: pre-commit run --all-files

Jó, ha van egy fogalmi csővezeték, amely bármilyen CI rendszerrel működik, de ha a GitHub műveleteket használja, akkor nem kell aggódnia; használja aHivatalos akció.

jobs:
  pre-commit:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
    - uses: actions/setup-python@v3
    - uses: pre-commit/action@v3.0.1

A CI-integrációval a csomópont befejeződik, és ugyanazt az érvényesítést alkalmazzák a fejlesztői környezetben, mint a CI-környezetben.

következtetés

Megértés ottvanhogy jobb módja legyen, mint a kézi ellenőrzések és a "oops" elkötelezettség, felfedeztük, hogyanpre-commitátalakítja a fejlesztési munkafolyamatot.

Azáltal, hogy automatikusan ellenőrzi a fehér térbeli hibákat és a titkos felismeréstől a kódformázásig és a szalagolásig, az előre elkötelezettség a kódminőség fáradhatatlan helyi őrzőjeként működik, amely még a CI/CD csővezetékekbe is „zökkenőmentesen” integrálható, hogy végső minőségi kaput szolgáljon.