Git Notes: Git का सबसे शानदार और सबसे नापसंद किया गया फीचर (2022)

 (tylercipriani.com)
3 पॉइंट द्वारा GN⁺ 2025-06-23 | 1 टिप्पणियां | WhatsApp पर शेयर करें
  • Git notes Git objects को बदले बिना अलग namespace में metadata जोड़ने की सुविधा है, लेकिन कम usability और सीमित adoption के कारण इसका व्यापक उपयोग नहीं होता
  • पुराने commit messages को बदले बिना नई जानकारी जोड़ी जा सकती है, इसलिए यह review, build, ticket जानकारी जैसे automation systems द्वारा छोड़े गए records के लिए अच्छी तरह उपयुक्त है
  • Git project और Gerrit notes का असल उपयोग करते हैं, जिससे हर commit के लिए mailing list discussions, test results और reviewer जानकारी git log में देखी जा सकती है
  • Google का git-appraise git notes के ऊपर distributed code review लागू करता है, ताकि review requests, comments, reviews और merge स्थानीय रूप से किए जा सकें
  • GitHub ने 2014 में commit notes दिखाना बंद कर दिया, और blob/tree notes के लिए Git internal commands की समझ चाहिए, इसलिए project history को distribute करने की संभावना होने के बावजूद इन्हें इस्तेमाल करना कठिन है

Git objects को बदले बिना metadata

  • Git notes Git द्वारा track किए जाने वाले objects में अलग metadata store करने की सुविधा है
    • लक्ष्य सिर्फ commits नहीं, बल्कि blob और tree भी शामिल हैं
    • object को खुद modify किए बिना अलग namespace में जानकारी जोड़ी जाती है
  • history में पहले से शामिल commit messages को आम तौर पर सुरक्षित तरीके से बदलना मुश्किल होता है, लेकिन notes का उपयोग करके पुराने commits में भी नई जानकारी जोड़ी जा सकती है
    • नीचे की तरह git notes add -m से note जोड़ा जा सकता है 
      git notes add -m 'Acked-by: <tyler@tylercipriani.com>'
    • इसके बाद git log में उस commit के नीचे Notes: block के रूप में दिखता है
  • Scott Chacon ने 2010 में GitHub.blog पर notes को अन्य developers के साथ बातचीत से ज्यादा ticket/build systems जैसे automated records जोड़ने के लिए अधिक उपयुक्त feature माना

वास्तविक उपयोग और रुकावटें

  • Git project हर commit को mailing list discussion से जोड़ने के लिए notes का उपयोग करता है
    • उदाहरण commit के Notes (amlog) में Message-Id होता है, और यह value patch discussion thread तक ले जाती है
  • notes का उपयोग commit या branch के अनुसार work time tracking, git log में review/test जानकारी जोड़ने, और fully distributed code review जैसे उद्देश्यों के लिए भी किया जाता है
  • Gerrit का reviewnotes plugin code review metadata को Git के अंदर offline देखने योग्य बनाता है
    • notes fetch करने और दिखाने के commands ये हैं 
      git fetch origin refs/notes/review:refs/notes/review
git log --show-notes=review
    • दिखाई जाने वाली जानकारी में Verified+1, Verified+2, Code-Review+2, Submitted-by, Submitted-at, Reviewed-on, Project, Branch आदि शामिल हैं
  • Google का git-appraise git notes के ऊपर बना “fully distributed code review” system है
    • यह GitHub, GitLab जैसे code forge से स्वतंत्र रूप से काम करता है
    • change review requests, changes पर comments, reviews और merge स्थानीय computer पर किए जा सकते हैं
    • इसमें web interface भी शामिल है
  • सबसे बड़ी कमजोरी usability है
    • GitHub ने 2014 में commit notes दिखाना बंद कर दिया
    • commit notes के लिए gitconfig settings से automatic fetch और git log display को कुछ हद तक आसान बनाया जा सकता है 
      git config --add \
remote.origin.fetch \
'+refs/notes/*:refs/notes/*'

git config \
notes.displayRef \
'refs/notes/*'
    • blob या tree में notes store करने के लिए Git की plumbing से परिचित होना जरूरी है
  • Git code history को distribute करता है, लेकिन Git repository की बहुत-सी value GitHub जैसे forge के अंदर बंद रहती है
    • git notes सिर्फ code ही नहीं, बल्कि पूरे project history को distribute करने का रास्ता बन सकते हैं

संबंधित पढ़ाई

1 टिप्पणियां

 
GN⁺ 2025-06-23
Hacker News की रायें

  • एक और कम-ज्ञात फीचर git trailers है: https://alchemists.io/articles/git_trailers
    यह key-value संरचित डेटा है जिसे commit बनाते समय शामिल किया जा सकता है, और कुछ systems इसे metadata जोड़ने के लिए इस्तेमाल करते हैं। उदाहरण के लिए Gerrit, Change-Id जोड़ने के लिए इसी फीचर का उपयोग करता है

    • दूसरे systems में मिलते-जुलते फीचर के तौर पर PostgreSQL COMMENT है: https://www.postgresql.org/docs/17/sql-comment.html
      यह PostgreSQL के कई database objects में text जोड़ने देता है। अच्छा होगा अगर PostgreSQL में भी editable, structured key-value रूप में database object metadata का फीचर हो
    • हाल ही में पता चला कि GitHub [skip ci] डालने के विकल्प के तौर पर git trailers इस्तेमाल करता है, शायद इसलिए कि commit message consume करने वाले downstream systems के लिए इसे हटाना आसान हो: https://docs.github.com/en/actions/managing-workflow-runs-an...
      यह क्यों enforce करता है कि वह आखिरी trailer ही हो, पता नहीं; शायद regex की वजह से हो
    • मैंने अपने branch के commits में वे commits mark करने के लिए git notes इस्तेमाल किया था जिन पर unit tests चलाए थे, और script से ऐसे commits skip करवाए थे
      open source upstream के साथ काम करते समय, जब git rebase -i से branch को पूरी तरह polish करना चाहता था, तब यह उपयोगी था। अब लगता है कि वह जानकारी git trailers में रखना बेहतर होगा। Change-Id के मामले में, अच्छा होगा अगर Git में खुद ऐसे identifiers हों जिन्हें tools भी समझ सकें। commit message से commit identify करना fragile है, खासकर MR में जब message बदला जा सकता हो। commit ID किसी commit को uniquely identify करता है, लेकिन जब वही बदलाव किसी दूसरे commit के ऊपर ले जाया जा सकता हो, तब वह उपयोगी identifier नहीं रहता। हालांकि trailers असली commit का हिस्सा होते हैं और notes नहीं, इसलिए मेरे इस्तेमाल वाले case में यह अच्छा विकल्प नहीं होगा
    • दिलचस्प है, इस फीचर के बारे में नहीं जानता था। मुझे conventional commits पसंद हैं, और trailers ऐसा metadata जोड़ने का बेहतर तरीका लगते हैं
      सोच रहा हूँ कि commit message में manually डालना और --trailer flag इस्तेमाल करना functionally एक जैसा है या नहीं
    • GOOG में काम करते समय जो Gerrit इस्तेमाल करता था, उसकी बहुत याद आती है, लेकिन 2020s के हिसाब से deployment story काफ़ी खराब है
      local पर instance चलाकर उसे GitHub पर hosted repository के साथ integrate करने की कोशिश की, लेकिन सिर्फ निराशा मिली। सोचता हूँ क्या कोई ऐसा alternative है जो commits के पार changes tracking वगैरह GitHub से बेहतर handle करता हो, ज्यादा actively develop हो रहा हो और GitHub integration-friendly भी हो। GitHub के code review tools मुझे सच में नापसंद हैं

  • Forgejo भी इस साल जनवरी में आए version 10 से support करता है: https://forgejo.org/2025-01-release-v10-0/#new-features
    https://codeberg.org/forgejo/forgejo/pulls/4753

  • यह सच में शानदार दिखता है, लेकिन जानना चाहता हूँ कि amend या rebase जैसे history rewriting features, जो असल में commit को संशोधित copy से बदल देते हैं, notes के साथ कैसे काम करते हैं
    लगता है notes किसी specific commit, tree या blob ID से जुड़ते हैं। सोचता हूँ कि git rebase आदि इतने smart हैं कि notes को नए commits पर copy कर दें, या वे बस गायब हो जाते हैं। interactive rebase में कई commits को squash करके एक कर दें तो क्या होता है, यह भी सवाल है। blobs और trees पर notes लगाने में भी वही समस्या लगती है। यह repository की files या directories पर metadata लगाने जैसा महसूस होता है, लेकिन असल में यह specific content से जुड़ता है। उदाहरण के लिए अगर "Hello world!" string वाले blob पर note लगाएँ, तो क्या Git उस content वाली सभी files से note जोड़ देगा? और अगर किसी file को "Hello, world!" में बदल दें, तो क्या notes खो जाएँगे?

    • यह configurable है। default रूप से amend और rebase operations notes को आगे copy करते हैं। notes.rewrite entries git-config(1) में देखी जा सकती हैं

  • शायद 10 साल से Git इस्तेमाल कर रहा हूँ, लेकिन पता नहीं था कि git notes मौजूद है। बढ़िया
    “हर forge code review metadata को Git के अंदर offline इस्तेमाल करने लायक बनाए” वाली request शायद GitHub जैसे commercial forges पर ज्यादा असर नहीं करेगी। जैसा आपने खुद कहा, Git repository की बहुत-सी value GitHub जैसे forges में locked है। for-profit कंपनियाँ आम तौर पर अपने added value को generic बनाने में खास उत्साहित नहीं होतीं। मैं GitHub को दोष नहीं दे रहा; वे बेहतरीन service और बहुत generous free tier देते हैं, और अगर आप migrate करना चाहें तो API के ज़रिए सारा data निकालने देते हैं—इस लिहाज से वे अच्छा कर रहे हैं। बात बस commercial operations की nature की है

    • पहले एक नई service शुरू करनी होगी जो इस फीचर को differentiator के तौर पर पेश करे, फिर competitors भी catch up करने के लिए यह फीचर वापस जोड़ सकते हैं

  • Git notes तभी शानदार लगते हैं जब commit बन जाने और दूसरों को दिख जाने के बाद उसमें अक्सर text जोड़ना हो
    Acked-By और mailing list discussion link वाले उदाहरण अच्छे उदाहरण नहीं लगते। दोनों के बारे में commit बनाते समय पहले से पता होने की संभावना ज्यादा है। Git commit message में व्यावहारिक रूप से लंबाई की सीमा लगभग नहीं होती, इसलिए forge पर हुई commit-संबंधी चर्चा को सीधे commit message में ही कॉपी किया जा सकता है। मेरे हिसाब से बेहतर उदाहरण वह है जब बाद में revert किए गए commit में git note जोड़ा जाए

    • एक आम failure mode यह है कि commit message पूरे आत्मविश्वास से घोषणा करता है कि उसने ऐसा bug fix किया है जिसे उसने असल में fix नहीं किया। और fix से बने chain bugs को एक ही bug से जोड़ देता है
      शायद मैं ही अजीब हूं, लेकिन मैंने बहुत सारे colleagues देखे हैं जो यह याद करने के लिए comments या annotate ठीक से नहीं देखते कि code शुरू में क्यों लिखा गया था। वे बस तुरंत बदल देते हैं और उम्मीद करते हैं कि समस्या उनसे न जुड़े। लेकिन अगर आपने bug fix का इंतज़ार कर रहे नाराज़ customer को संभाला हो, और कुछ ही समय बाद वही bug फिर वापस आते देखा हो, तो bug fix में ज्यादा सावधानी आ सकती है। कई bugs को एक साथ fix करने के लिए अक्सर refactoring चाहिए होती है, और refactoring नई feature opportunities या performance improvements भी खोल सकती है
    • commit पर discussion, यानी review और commit approval (Ack), commit बनने से पहले नहीं हो सकते
      बाद में revert किए गए commit पर निशान छोड़ने के लिए commit message बेहतर है। किसी file पर blame करने से उस file का latest change दिखता है, और अगर किसी commit ने दूसरे commit के बदलाव को revert किया है, तो ज्यादा नया revert commit blame में दिखाई देगा
    • commit बन जाने के बाद भी discussion जारी रह सकती है

  • यह knowledge की कमी नहीं, UI problem है। अगर GitHub UI notes दिखाने लगे तो usage तुरंत बहुत बढ़ जाएगा

    • काश GitHub इसे support करता

  • “Git की सबसे शानदार लेकिन कम पसंद की गई feature” कई हैं। जैसे bisect, pickaxe, reflog, range-diff, archive, annotated tags आदि
    अफसोस है कि बहुत से लोग Git को बस एक चमकदार Google Drive जैसा मानते हैं, इसलिए ये features अक्सर भूल जाते हैं

    • Git notes वैसे भी feature tracking के लिए redundant हैं, क्योंकि इसके लिए higher-level project management tool चाहिए। roadmap, feature hierarchy, non-technical details चाहिए होते हैं—किसी बड़े tracker या Jira के बारे में सोचिए
      फिर भी मुझे यह ठीक लगता है। Unix philosophy है कि एक चीज़ पर focus करो और उसे अच्छी तरह करो
    • कई मामलों में ये features वास्तव में इतने useful नहीं होते, और core tools के आसपास की सजावट जैसे होते हैं जो असली worker का काम करते हैं
    • मुझे लगा था कि list में दिए सारे features जानता होऊंगा, लेकिन pickaxe ने अचानक पकड़ लिया। मुझे इतना overconfident नहीं होना चाहिए

  • LibreOffice project में Apache OpenOffice repository के हर commit को track करने के लिए Git notes का इस्तेमाल हुआ था
    उस repository को LibreOffice Git repository की branch के रूप में mirror करते हुए, उन्होंने दर्ज किया कि हर commit irrelevant change है या नहीं—जैसे build system change जिसे LibreOffice ने बहुत पहले बेहतर चीज़ से बदल दिया था—या वह change पहले से LibreOffice में मौजूद change का duplicate है, या दुर्लभ cases में LibreOffice में स्वीकार किया गया और किस commit के रूप में cherry-pick किया गया। इसे अभी भी https://cgit.freedesktop.org/libreoffice/core/log/?h=aoo/tru... पर सीधे देखा जा सकता है, और यह Git frontend अब भी notes दिखाता है। कुछ साल पहले से उन्होंने इस तरह की change tracking बंद कर दी है, शायद इसलिए कि Apache OpenOffice में changes की गति बहुत धीमी हो गई और कुछ ही changes को cherry-pick करके मिलने वाला फायदा ज्यादा नहीं रहा

  • यह सबसे शानदार लेकिन कम पसंद की गई feature नहीं, बल्कि ऐसी gimmick feature के ज्यादा करीब है जो बहुत खास cases में अच्छी हो सकती थी, जैसे पूरी company को सिर्फ developers की team के रूप में चलाना
    जो जरूरी है वह commit message में जाता है, और अलग system के ticket को reference करना bug नहीं बल्कि feature है। क्योंकि JIRA या दूसरे systems non-developers से communicate करने के लिए इस्तेमाल होते हैं। उदाहरण के लिए business analyst के पास code या repository access बिल्कुल नहीं होता, और support staff के पास भी repository और code access नहीं होता। non-developers के लिए notes देखने और edit करने वाला frontend बनाया जा सकता है, लेकिन फिर भी उसका खास मतलब नहीं होगा। BA या support team आदि को specific commits में दिलचस्पी नहीं होती, और कोई feature किसी एक commit से ठीक-ठीक match हो सकता है, लेकिन आम तौर पर ऐसा नहीं होता। अगर कई repositories इस्तेमाल हों और एक feature कई services में फैला हो, तो git notes काफी बेकार हो जाते हैं, और आखिरकार external system का reference चाहिए होता है

    • मुझे तो उल्टा यह अजीब लगता है कि business analysts या support staff को code और repository access नहीं दिया जाता। अपने product को black box की तरह treat करने से फायदा क्या है?
      लेकिन यही mainstream है। कभी-कभी उसी monorepo को share करने वाली दूसरी team का analyst मुझसे ऐसा सवाल पूछता है जिसका जवाब code की एक line से तुरंत दिया जा सकता है। वह analyst technical भी है और SQL भी जानता है, और हमारा code बहुत idiomatic और high-level तरीके से लिखा गया है। फिर भी culture अपनी अंतर्निहित inefficiency से मरने तक खुद को बदल नहीं पाता
    • commit message में न आने वाला लेकिन संबंधित commit से बाहर का data बहुत होता है। जैसे tests pass हुए या नहीं[1], manual test records, code review के iterations, 6 महीने से पुराने problematic commit को खंगालते समय छोड़े गए notes वगैरह
      [^1] https://news.ycombinator.com/item?id=44348438

  • GitLab में notes support मांगने वाली 9 साल पुरानी feature request हाल में बंद कर दी गई: https://gitlab.com/gitlab-org/gitlab/-/issues/15029
    दुर्भाग्य से पढ़ने के लिए login करना होगा, लेकिन कोई भी gitlab.com account काम कर जाना चाहिए

    • एक और issue भी है जिसमें ज्यादा complete proposal है: https://gitlab.com/gitlab-org/gitlab/-/issues/216351
    • जिन्हें curiosity हो उनके लिए: यह complete होकर बंद नहीं हुआ, बल्कि छोड़े रहने के कारण बंद हुआ: “फिलहाल focus इस area पर नहीं है, इसलिए हम इस feature request को बंद कर रहे हैं”