Garis pertahanan pertama anda untuk kod bersih adalah pra-komitmen: Bagaimana untuk menetapkan ia

Pernah tidak sengaja mendorong rahsia ke repository? atau mungkin anda telah mendorong kod yang tidak diformat, hanya untuk perlu mencipta komit "linting" seterusnya? kita semua telah berada di sana. kesilapan kecil ini boleh membawa kepada paip CI / CD yang gagal dan penundaan yang mengecewakan, semua kerana pemeriksaan yang boleh dijalankan secara tempatan.

Git hooks adalah alat yang berkuasa untuk mengelakkan masalah ini dengan menjalankan skrip sebelum anda berkomitmen atau mendorong.

Pre-commit ialah kerangka kerja yang mudah digunakan untuk mengurus dan berkongsi git hooks pelbagai bahasa, membantu anda menangkap masalah sebelum mereka meninggalkan stesen kerja anda.

Memulakan: Setup yang betul

Sebelum anda boleh memanfaatkan kuasa pra-komit, anda perlu memasang dan mengkonfigurasikannya untuk projek anda.

pemasangan

Terdapat beberapa cara untuk memasang pre-commit:

• MacOS dan Linux :

brew install pre-commit

• Python / Pip (Cross-Platform) dalam talian

pip install pre-commit

• Kaedah lain: Untuk pemasangan menggunakan Conda atau pada Windows, sila rujuk kepada Dokumentasi Rasmi.

Setup spesifik projek (Cara Standard)

Ini adalah pendekatan yang paling biasa untuk membolehkan pra-komitmen dalam projek tertentu:

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. Perintah ini memasang git hooks ke dalam direktori .git/hooks repository anda. Mulai sekarang, pra-komit akan menjalankan ceknya secara automatik sebelum setiap komit yang anda buat dalam repository tertentu ini.

Pengaturan Global (Metode “Set It and Forget It”)

Jika anda kerap memulakan projek baru atau mengkloning repositori dan mahu pra-komitmen aktif secara lalai (jika ada konfigurasi), anda boleh menetapkan secara global.init.templateDirciri yang

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

(Anda boleh memilih direktori yang berbeza jika anda suka, hanya pastikan ia konsisten dalam langkah seterusnya.)

Memulakan Pre-commit dalam Template Directory: Jalankan perintah berikut:

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

(Jika anda memilih direktori yang berbeza dalam langkah sebelumnya, tukar~/.git-templateOleh yang demikian.)

Ini mempunyai Kelebihan utama: Dengan setup global ini, mana-mana repository baru yang anda memulakan (git init) atau klon akan secara automatik mempunyai pre-commit's hook dipasang..pre-commit-config.yamlfail, pra-komitmen hanya tidak akan melakukan apa-apa, jadi ia selamat untuk mengaktifkan secara global.

Walau bagaimanapun, saya suka melangkah lebih jauh dengan menambah hook lalai~/.git-template/hooks/pre-commityang akan gagal secara sistematik jika repository tidak mempunyai.pre-commit-config.yamlBerikut ialah kandungan hook.

#!/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

Membina konfigurasi anda (.pre-commit-config.yaml)

Titik utama pra-komitmen ialah.pre-commit-config.yamlfail. fail ini, ditempatkan di akar repository anda, memberitahu pra-komit yang memeriksa untuk dijalankan.

# 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

Struktur asas yang dijelaskan

Konfigurasi tipikal melibatkan senarai repositori, masing-masing dengan hooks tertentu:

• repos: Ini adalah kunci peringkat atas yang mengambil senarai peta repository. Setiap item dalam senarai menentukan repository Git yang mengandungi hooks pra-komit.

• repo: URL repository hosting hooks (contohnya, https://github.com/pre-commit/pre-commit-hooks). Ini adalah cara yang sangat baik untuk menguruskan ketergantungan. Apabila anda tahu lebih lanjut mengenai alat ini, anda boleh pergi ke repository.

• rev: Ia menentukan versi hooks yang akan digunakan, dengan pinning kepada sama ada tag Git, SHA, atau cabang. tetapi disyorkan untuk sentiasa menggunakan tag tertentu atau SHA (bukan cabang seperti master) untuk memastikan linting anda tidak terkejut apabila repository jauh dikemas kini.

• Hooks: Senarai di bawah setiap entri repo. Setiap item di sini mendefinisikan hook tertentu untuk digunakan dari repository itu.

• id: Pengenal unik hook (contohnya, trailing-whitespace, check-yaml). Anda boleh mencari ID hook yang tersedia dalam dokumen repository hook. atau hanya .pre-commit-hooks.yaml di akar repo.

Konfigurasi permulaan yang praktikal

Berikut ialah asas.pre-commit-config.yamlUntuk contoh ini, saya mengesyorkan anda pergi ke Github dan melihatPre-komit/pre-komit-hooks/blob/main/.pre-komit-hooks.yamlBerikut ialah senarai kelengkapan yang mudah yangpre-commitpasukan telah melaksanakan, dan di mana anda boleh mencariiddaripada setiap hook yang relevan yang anda mungkin mahu gunakan.

Saya katakantrailing-whitespacedanend-of-file-fixersangat berguna, jadi konfigurasi akan kelihatan seperti ini.

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: ...

Nota: Versi untuk hooks berubah seiring dengan masa.Ia adalah amalan yang baik untuk kadang-kadang memeriksapre-commit-hooksrepository (atau mana-mana repositori hook lain yang anda gunakan) untuk tag versi stabil terkini dan mengemas kinirevAtau mempunyai automatik di tempat, seperti Renovate atau Dependabot, untuk mengemas kini mereka secara kerap.

Anda boleh mencari senarai besar hooks yang sedia ada padaLaman web Pre-CommitDari pengalaman saya, senarai ini jauh daripada meluas; sebaliknya, saya lebih suka memeriksa alat-alat yang saya suka menggunakan.pre-commit-hooks.yamlLihat apakah hoki boleh didapati

Penting untuk tahu apabila menggunakan pra-komitmen

Sebaik sahaja anda selesa dengan asas-asas, pra-komitmen menawarkan ciri-ciri yang lebih maju untuk menyesuaikan aliran kerja anda.

Menjalankan Hooks secara manual

Apabila hooks berjalan secara automatik padagit commit, anda mungkin ingin memicu mereka secara manual pada masa-masa lain:

• Menjalankan hook tertentu: Untuk melaksanakan hook tunggal (contohnya, untuk menguji konfigurasinya atau memohon perubahan tanpa berkomitmen), gunakan:

pre-commit run <hook_id>

Penggantian<hook_id>dengan ID sebenar daripada fail konfigurasi anda.)

• Menjalankan pada semua fail: Untuk menjalankan semua hooks yang dikonfigurasikan pada setiap fail yang dilacak dalam repository anda (bukan hanya perubahan berturut-turut), gunakan:

pre-commit run --all-files

Ini berguna untuk pembersihan permulaan atau apabila menambah hooks baru kepada projek yang sedia ada.

Mencipta Hooks tempatan anda sendiri

Kadang-kadang, anda mungkin mempunyai skrip atau cek spesifik projek yang bukan sebahagian daripada repositori hook awam. Pre-commit membolehkan anda menentukan hooks "lokal".

1. Tulis skrip anda: Buat skrip anda (contohnya skrip shell, skrip Python) dalam repository anda. Untuk contoh ini, katakan anda mencipta my_custom_script.sh.
2. Tentukan dalam .pre-commit-config.yaml: Tambah entri hook tempatan kepada konfigurasi anda:

# .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

Ini memberitahu pra-komitmen untuk berlarimy_custom_script.shuntuk sebarang perubahan dalam Python (.pyFilem : Thelanguage: scriptJenis adalah sangat fleksibel; untuk persekitaran tertentu seperti Python atau Node, anda boleh menentukan mereka untuk menguruskan ketergantungan jika perlu.bashkepada Hooks.

Walau bagaimanapun, pra-komitmen sangat pintar mengenai persekitaran kerja, kerana ia mewujudkan persekitaran runtime yang terpencil untuk alat dan ketergantungan yang diperlukan.

Tidak semua hook, sayangnya, telah memanfaatkan ciri ketergantungan, dan anda mungkin perlu memasang alat sendiri untuk dapat menjalankan hook (saya berfikir tentang terraform, contohnya)

Pre-komitmen dalam pasukan dan persekitaran CI / CD

Walaupun pre-commit bersinar pada mesin pengembang individu, faedahnya berlipat-lipat apabila disepadukan ke dalam aliran kerja pasukan dan paip CI / CD. Walaupun dengan pre-commit hooks dipasang secara tempatan, seseorang mungkin secara tidak sengaja berkomitmen tanpa hooks (contohnya, menggunakangit commit --no-verify) atau mempunyai konfigurasi hook yang usang. paip CI / CD anda boleh bertindak sebagai penjaga pintu utama.

Dengan menjalankan pemeriksaan pra-komitmen dalam paip CI anda, anda memastikan bahawa tiada kod yang melanggar piawaian projek anda disatukan.

pre-commit run --all-files

Perintah ini memeriksa semua fail dalam repository, bukan sahaja yang diubahsuai, memastikan pengesahan yang menyeluruh.

Langkah Pipeline CI konseptual (contohnya, Tindakan GitHub):

# 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

Ia bagus untuk mempunyai paip konsep yang berfungsi dengan mana-mana sistem CI, tetapi jika anda menggunakan tindakan GitHub, anda tidak perlu bimbang; gunakanTindakan rasmi.

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

Dengan integrasi CI, loop selesai, dan pengesahan yang sama digunakan dalam persekitaran pengembang seperti dalam persekitaran CI.Jika paip gagal, pastikan ia secara tempatan dengan menjalankan pra-komitmen.

Kesimpulan

Menyedari di sanamempunyaiuntuk menjadi cara yang lebih baik daripada pemeriksaan manual dan “oops” komited, kami telah meneroka bagaimana iapre-commitMengubah aliran kerja pembangunan anda.

Dengan mengotomatiskan pemeriksaan untuk segala-galanya dari kesilapan ruang putih dan pengesanan rahsia kepada pemformatan kod dan pengikat, pra-komit bertindak sebagai penjaga kualiti kod tempatan tanpa lelah anda yang bahkan boleh disepadukan "selesa" ke dalam paip CI / CD untuk berkhidmat sebagai gerbang kualiti akhir.