הפיצ'ר של git notes קיים בגיט כבר עשר שנים בערך אבל מעט אנשים מכירים אותו או משתמשים בו. בפוסט זה נראה מהם notes ומה הפקודות המרכזיות לעבודה איתם.

1. מי צריך פתקים

אתגר משמעותי בעבודה עם גיט הוא שקומיטים אינם ניתנים לעריכה. נכון, אפשר למחוק קומיט וליצור אחר במקומו (עם פקודות כמו ריבייס, אמנד, צ'רי-פיק), אבל ממש לקחת קומיט קיים שדחפתי לשרת ושאחרים התבססו עליו ובנו ממנו קומיטים שלהם, ולשנות משהו בהודעה שלו, זה כבר לא פשוט.

וכך נוצרו מנגנונים שעוזרים לנו להוסיף גמישות לגרף הקומיטים - מנגנונים כמו בראנצ'ים, תגיות וגם פתקים.

פתק הוא טקסט חופשי שאני יכול להדביק על קומיט. הפתק יופיע בלוג (אם ארצה להציג אותו שם), הוא ניתן למחיקה, עריכה והזזה ואני יכול לחפש קומיטים לפי טקסט שיש בפתקים שלהם.

ולמה זה טוב? הנה כמה דוגמאות:

1. אם יש לי סקריפט שמריץ Deployment אוטומטי לסביבת בדיקות אחרי שעשיתי קומיט, אני יכול להדביק את הפלט של הסקריפט הזה בתור פתק לקומיט אחרי שהוא עושה דיפלוי. בצורה כזאת אני יכול לוודא שה deploy הצליח ולהיזכר אחר כך איזה קומיטים נכנסו ומתי לסביבת הבדיקות.

2. אותו סקריפט יכול לעשות deploy לסביבת פרודקשן, ואז הוא שוב יוסיף לי הערה לקומיט שהקוד נכנס לסביבת פרודקשן.

3. הרבה פעמים אני משתמש בלוג של גיט כדי לייצר רשימת שינויים כשאני מוציא גירסה. את הטקסט של רשימת השינויים אני רוצה לערוך גם אחרי שיצרתי את הודעת הקומיט, ולכן אני יכול להוסיף פתק על כל קומיט מה השינויים שהוא הביא, לערוך את הפתקים האלה כשצריך ובסוף להוציא רשימת שינויים מסודרת.

4. מאגרים מסוימים כוללים Pipelines שמריצים בדיקות אוטומטיות על כל קומיט, ופרויקטים אחרים מעסיקים אנשי QA שיריצו בדיקות בצורה ידנית. בשני המקרים התוצאה של הבדיקה לא יכולה להופיע בתור הודעת הקומיט (כי היא לא היתה זמינה כשעשינו קומיט), אבל אנחנו יכולים להדביק אותה בתור פתק לקומיט המתאים. אחר כך נוכל לחפש בין תוצאות הבדיקות או לסנן רק קומיטים בהם כל הבדיקות עברו.

2. איך משתמשים בפתקים

פתק הוא מידע שנשמר במאגר של גיט בקובץ נפרד מהקומיט. אנחנו יכולים להוסיף כמה פתקים שרוצים על כל קומיט בתנאי שהם יהיו ב"נושאים" שונים.

אני יוצר מאגר ראשון בשביל הדוגמה עם הפקודות:

$ git init .
$ git commit --allow-empty -m 'initial commit'
$ git commit --allow-empty -m 'created homepage'
$ git commit --allow-empty -m 'added about page'
$ git commit --allow-empty -m 'added admin panel'
$ git commit --allow-empty -m 'allow editing header from the admin pages'

התוצאה היא:

$ git log --oneline
0fa947b allow editing header from the admin pages
f4fa771 added admin panel
4126289 added about page
b4a7379 created homepage
ebddbeb initial commit

עכשיו בואו נוסיף כמה פתקים. נדמיין שיש לנו סקריפט שיודע לשלוח את הפרויקט לסביבת פרודקשן אחרי כל קומיט, ואותו סקריפט רוצה לדווח שהוא עשה את העבודה.

הפקודה הבאה מוסיפה פתק מסוג deployment לקומיט הראשון במאגר:

$ git notes --ref=deploy append ebddbeb -m 'pushed to production 22/10/22 10:00'

והפקודה הבאה תוסיף פתק דומה לקומיט השני:

$ git notes --ref=deploy append b4a7379 -m 'pushed to production 25/10/22 10:00'

עכשיו נניח שיש לנו סקריפט נוסף שמריץ בדיקות אוטומטיות. בשני הקומיטים הראשונים לא היו עדיין בדיקות אבל בקומיט השלישי כבר כתבתי 10 בדיקות, הסקריפט הריץ אותן וכולן עברו. אני יכול לדמיין את הפקודות הבאות שמוסיפות פתקים רלוונטים מאותו סקריפט בדיקות:

$ git notes --ref=testing append ebddbeb -m 'no tests found'
$ git notes --ref=testing append b4a7379 -m 'no tests found'
$ git notes --ref=testing append 4126289 -m 'performed 10 tests. All passed'

עכשיו שכל הפתקים במקום אני יכול להציג את הלוג ולהוסיף לו פתקים מסוג מסוים. לדוגמה זה הלוג בתוספת כל הפתקים מסוג testing:

0fa947b allow editing header from the admin pages
f4fa771 added admin panel
4126289 added about page
Notes (testing):
    performed 10 tests. All passed

b4a7379 created homepage
Notes (testing):
    no tests found

ebddbeb initial commit
Notes (testing):
    no tests found

וכדי להציג את כל הפתקים מכל הסוגים אני יכול להשתמש בכוכבית:

$ git log --notes="*"

גם grep עובד על פתקים ולכן אני יכול לסנן רק קומיטים שמכילים את הטקסט All passed בפתק הבדיקות:

$ git log --notes=testing --oneline --grep "All passed"

4126289 added about page
Notes (testing):
    performed 10 tests. All passed

3. שליחת פתקים לשרת מרוחק

בעבודה עם מאגר מרוחק אולי לא תשמחו לשמוע שהפתקים אינם נשלחים כברירת מחדל למאגר בכל push שאתם מפעילים. הפקודה הבאה דוחפת את המאגר יחד עם הפתקים:

git push origin "refs/notes/*"

וגם במשיכה ממאגר מרוחק לא תקבלו את הפתקים, ובשביל למשוך אותם תצטרכו להפעיל:

git fetch origin "refs/notes/*:refs/notes/*"

אם מוגדר לפרויקט שלכם שרת מרוחק בשם origin, הפקודות הבאות יגרמו לכל פעולת push ו fetch לכלול גם את הפתקים

$ git config --add remote.origin.push '+refs/notes/*:refs/notes/*'

$ git config --add remote.origin.fetch '+refs/notes/*:refs/notes/*'