From 6179aaa54652eda852d0b694c3538bfe92c2e422 Mon Sep 17 00:00:00 2001
From: Robert Rosca <robert.rosca@xfel.eu>
Date: Mon, 8 Feb 2021 11:22:54 +0100
Subject: [PATCH] Add comments to clarify non-standard sections

---
 .gitlab-ci.yml          | 5 +++++
 .pre-commit-config.yaml | 4 ++++
 2 files changed, 9 insertions(+)

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index e25f8e359..feee5b658 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -7,10 +7,15 @@ checks:
   only: [merge_requests]
   script:
     - export PATH=/home/gitlab-runner/.local/bin:$PATH
+    # We'd like to run the pre-commit hooks only on files that are being
+    # modified by this merge request, however
+    # `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` is a 'premium' feature according to
+    # GitLab... so this is a workaround for extracting the hash
     - export CI_MERGE_REQUEST_TARGET_BRANCH_SHA=$(git ls-remote origin $CI_MERGE_REQUEST_TARGET_BRANCH_NAME | cut -d$'\t' -f1)
     - export FILES=$(git diff $CI_COMMIT_SHA  $CI_MERGE_REQUEST_TARGET_BRANCH_SHA --name-only | tr '\n' ' ')
     - echo "Running pre-commit on diff from  $CI_COMMIT_SHA to $CI_MERGE_REQUEST_TARGET_BRANCH_SHA ($CI_MERGE_REQUEST_TARGET_BRANCH_NAME)"
     - python3 -m pip install --user -r requirements.txt
+    #  Pass list of modified files to pre-commit so that it only checks them
     - echo $FILES | xargs pre-commit run --color=always --files
 
 pytest:
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 2e0147c1c..da0c4977b 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -23,6 +23,10 @@ repos:
     rev: 3.8.4
     hooks:
     - id: flake8
+      # If `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` env var is set then this will
+      # run flake8 on the diff from the current commit to the latest commit of
+      # the branch being merged into, otherwise it will run flake8 as it would
+      # usually execute via the pre-commit hook
       entry: bash -c 'if [ -z ${CI_MERGE_REQUEST_TARGET_BRANCH_SHA} ]; then (flake8 "$@"); else (git diff $CI_MERGE_REQUEST_TARGET_BRANCH_SHA | flake8 --diff); fi' --
   - repo: https://github.com/myint/rstcheck
     rev: 3f92957478422df87bd730abde66f089cc1ee19b  # commit where pre-commit support was added
-- 
GitLab