Git LFS
हर Arkvory रिपॉज़िटरी एक Git LFS सर्वर है। आपकी git रिपॉज़िटरी वहीं रहती है, उदाहरण के लिए GitHub, GitLab या Gitea पर। केवल वे बड़ी फ़ाइलें जिन्हें Git LFS ट्रैक करता है, और फ़ाइल लॉक, Arkvory में जाते हैं। LFS ऑब्जेक्ट साधारण आर्टिफ़ैक्ट हैं, इसलिए रिपॉज़िटरी अनुमतियाँ, कोटा, SHA-256 जाँच, बैकअप और मिरर उन पर लागू होते हैं।
git रिपॉज़िटरी सेट करें
आपको HTTPS वाले सर्वर का पता (HTTPS देखें), एक Arkvory रिपॉज़िटरी, उदाहरण के लिए games, और एक कुंजी (खाते और कुंजियाँ देखें) चाहिए।
- हर उस मशीन पर Git LFS इंस्टॉल करें जो रिपॉज़िटरी इस्तेमाल करती है, और प्रति उपयोगकर्ता एक बार
git lfs installचलाएँ। - git रिपॉज़िटरी की जड़ में
.lfsconfigफ़ाइल बनाएँ और उसे commit करें। यह पूरी टीम को Arkvory इस्तेमाल करवाता है:
[lfs]
url = https://arkvory.example/lfs/games- फ़ाइल पैटर्न ट्रैक करें। यह
.gitattributesलिखता है, जिसे आप भी commit करते हैं:
git lfs track "*.psd" "*.fbx" "*.wav" "*.uasset" "*.umap"
git add .gitattributes .lfsconfig- हमेशा की तरह commit और push करें। पहला अनुरोध क्रेडेंशियल माँगता है: साइन इन देखें।
किसी रिपॉज़िटरी का LFS पता हमेशा https://<host>/lfs/<repository> होता है।
उन फ़ाइलों को स्थानांतरित करने के लिए जो पहले से किसी दूसरे सर्वर पर LFS में हैं, पहले पुराने सर्वर से सभी ऑब्जेक्ट डाउनलोड करें, फिर lfs.url बदलें और उन्हें अपलोड करें:
git lfs fetch --all origin
git config lfs.url https://arkvory.example/lfs/games
git lfs push --all originसाइन इन
Arkvory अपनी कुंजी को HTTP Basic प्रमाणीकरण के पासवर्ड के रूप में लेता है। उपयोगकर्ता नाम की जाँच नहीं होती: कोई भी नाम इस्तेमाल करें। कुंजी Bearer टोकन के रूप में भी आ सकती है।
Git पहली बार सर्वर के 401 उत्तर देने पर अपने क्रेडेंशियल हेल्पर के ज़रिए उपयोगकर्ता नाम और पासवर्ड माँगता है। हेल्पर उन्हें सहेज लेता है: Windows और macOS पर Git Credential Manager, Linux पर credential.helper store या cache.
| कौन | कुंजी |
|---|---|
| डेवलपर | एक व्यक्तिगत एक्सेस टोकन। push और लॉक के लिए read-write स्कोप, केवल clone और pull के लिए read स्कोप। |
| बिल्ड सर्वर, CI | अनुमतियाँ में दी गई कार्रवाइयों वाली सेवा कुंजी |
Git क्रेडेंशियल प्रति होस्ट रखता है। Arkvory की कुंजी आपकी git रिपॉज़िटरी के होस्ट, उदाहरण के लिए GitHub, के क्रेडेंशियल की जगह नहीं लेती।
क्रेडेंशियल हेल्पर रहित CI रनर पर कुंजी को checkout की स्थानीय कॉन्फ़िगरेशन में रखें। तब कुंजी केवल उस वर्कस्पेस के .git/config में रहती है, कभी .lfsconfig में नहीं:
git config lfs.url "https://ci:${ARKVORY_KEY}@arkvory.example/lfs/games"कुंजी commit न करें। उसे लॉग में प्रिंट न करें। जॉब के बाद वर्कस्पेस हटा दें।
रोज़ का काम
Git LFS किसी भी LFS सर्वर की तरह काम करता है। आप जो कमांड इस्तेमाल करते हैं:
| कमांड | यह क्या करता है |
|---|---|
git push | कमिट push करने से पहले नए LFS ऑब्जेक्ट Arkvory में अपलोड करता है |
git clone, git pull, git checkout | वे ऑब्जेक्ट डाउनलोड करता है जिनकी वर्किंग ट्री को ज़रूरत है |
git lfs fetch --all | सभी ब्रांचों के ऑब्जेक्ट डाउनलोड करता है |
git lfs ls-files | ट्रैक की गई फ़ाइलें और उनकी छोटी ID सूचीबद्ध करता है |
git lfs push --all origin | सभी स्थानीय ऑब्जेक्ट फिर से अपलोड करता है। जो ऑब्जेक्ट Arkvory के पास हैं, वे नहीं भेजे जाते। |
जो ऑब्जेक्ट Arkvory के पास पहले से है, उसी ID और आकार के साथ, वह दोबारा नहीं भेजा जाता। रुकावट के बाद दोहराया गया push केवल वही भेजता है जो गायब है।
फ़ाइलें लॉक करें
बाइनरी एसेट मर्ज नहीं किए जा सकते। लॉक टीम को बताता है कि एक व्यक्ति एक फ़ाइल संपादित कर रहा है। लॉक Arkvory रिपॉज़िटरी से संबंधित हैं, किसी ब्रांच से नहीं।
git lfs lock Content/Maps/Level01.umap
git lfs locks
git lfs unlock Content/Maps/Level01.umap- उसी पथ पर दूसरा
git lfs lock"already created lock" संदेश के साथ विफल होता है और स्वामी का नाम बताता है। - जब लॉक बनाया गया तब स्वामी उपयोगकर्ता या सेवा खाते के नाम से दिखाया जाता है। फ़ाइल कुंजी अपनी ID दिखाती है।
- केवल स्वामी ही फ़ाइल अनलॉक करता है। किसी दूसरे के लॉक पर
git lfs unlock --forceके लिए रिपॉज़िटरी मेंartifact.deleteकार्रवाई वाली सेवा कुंजी चाहिए। व्यक्तिगत टोकन लॉक नहीं तोड़ सकते। - लॉक पथ git रिपॉज़िटरी का पथ है: 1024 अक्षरों तक, फ़ोल्डरों के बीच
/, और बिना खाली खंड,.या.., बैकस्लैश या कोलन। git lfs locksप्रति पेज 100 लॉक दिखाता है।
push से पहले जाँच चालू करें, ताकि git उन फ़ाइलों में बदलाव push करने से मना कर दे जिन्हें दूसरों ने लॉक किया है। यह सेटिंग प्रति सर्वर पता है:
git config lfs.https://arkvory.example/lfs/games.locksverify trueउन फ़ाइल प्रकारों को चिह्नित करें जिन्हें संपादन से पहले लॉक किया जाना चाहिए। तब Git LFS उन्हें तब तक रीड-ओनली रखता है जब तक आप उन्हें लॉक न करें:
git lfs track --lockable "*.umap" "*.uasset"push पर लॉक जाँच को write एक्सेस चाहिए, इसलिए रीड-ओनली टोकन इसका उपयोग नहीं कर सकता। लॉक सूचीबद्ध करने के लिए git lfs locks इस्तेमाल करें, जिसकी read एक्सेस अनुमति देती है।
Unity और Unreal युक्तियाँ
- Unity: टेक्स्ट एसेट (
.unity,.prefab,.asset) git में रखें और एसेट सीरियलाइज़ेशन को Force Text पर सेट करें। बड़ी बाइनरी को LFS में ट्रैक करें, उदाहरण के लिए*.png,*.psd,*.fbx,*.wav,*.mp4,*.exr. जिन टेक्स्ट फ़ाइलों को आप LFS में ट्रैक करते हैं, वे भी स्वीकार की जाती हैं। - Unreal Engine:
*.uasset,*.umapऔर बड़ी स्रोत फ़ाइलें ट्रैक करें, और*.uassetतथा*.umapको लॉक करने योग्य चिह्नित करें। - LFS लॉकिंग कमांड कॉल करने वाले एडिटर इंटीग्रेशन Git LFS के मानक फ़ाइल लॉकिंग प्रोटोकॉल का उपयोग करते हैं। Arkvory का परीक्षण
gitऔरgit-lfsकमांड-लाइन क्लाइंट के साथ किया जाता है। - दसियों गीगाबाइट के बदलते बिल्ड आउटपुट LFS में न रखें। उन्हें आर्टिफ़ैक्ट या
arkvoryctlके साथ रॉ फ़ाइलों के रूप में अपलोड करें। LFS ऑब्जेक्ट प्रतिधारण द्वारा कभी हटाए नहीं जाते, इसलिए वे हमेशा बने रहते हैं। - Unity प्रोजेक्ट जो बड़ा पुन: प्रयोग योग्य कोड या टूल साझा करते हैं, उनके लिए Unity पैकेज बेहतर हैं।
क्या संग्रहीत होता है
- एक LFS ऑब्जेक्ट Arkvory रिपॉज़िटरी में एक आर्टिफ़ैक्ट है। इसका नाम और इसकी पहचान इसकी सामग्री का SHA-256 है (LFS का
oid), और इसका लेबलlfsहै। ये आर्टिफ़ैक्ट आप कंसोल में आर्टिफ़ैक्ट के अंतर्गत देखते हैं। - Arkvory ऑब्जेक्ट प्राप्त करते समय आकार और SHA-256 सत्यापित करता है। यदि वे
oidसे भिन्न हों, तो अपलोड422के साथ विफल होता है और कुछ भी संग्रहीत नहीं होता। - एक ऑब्जेक्ट रिपॉज़िटरी से संबंधित होता है। दो Arkvory रिपॉज़िटरी उसी फ़ाइल की अपनी-अपनी प्रतियाँ रखती हैं।
- प्रतिधारण LFS ऑब्जेक्ट कभी नहीं हटाता, क्योंकि सर्वर यह नहीं देख सकता कि किन कमिट को अब भी उनकी ज़रूरत है। LFS ऑब्जेक्ट हटाने का कोई कमांड नहीं है। एसेट के पूरे इतिहास के लिए रिपॉज़िटरी का कोटा योजना-पूर्वक तय करें।
- लॉक डेटाबेस में पंक्तियाँ हैं। बैकअप उन्हें शामिल करते हैं।
अनुमतियाँ
व्यक्तिगत टोकन और फ़ाइल कुंजियों को रिपॉज़िटरी पर read या write एक्सेस मिलता है। सेवा कुंजियों को सटीक कार्रवाइयाँ मिलती हैं।
| ऑपरेशन | सेवा कुंजी कार्रवाइयाँ | व्यक्तिगत टोकन या फ़ाइल कुंजी |
|---|---|---|
डाउनलोड (clone, fetch, pull) | content.read | Read एक्सेस |
अपलोड (push) | upload.create | Write एक्सेस, टोकन स्कोप read-write |
| लॉक सूचीबद्ध करें | artifact.list | Read एक्सेस |
| अपने लॉक बनाएँ, सत्यापित करें और छोड़ें | upload.create | Write एक्सेस, टोकन स्कोप read-write |
किसी दूसरे का लॉक छोड़ें (--force) | artifact.delete | संभव नहीं |
push और pull करने वाले CI जॉब को content.read, upload.create और artifact.list चाहिए। केवल push कर सकने वाली कुंजी को फिर भी पता चलता है कि ऑब्जेक्ट मौजूद है, इसलिए वह उसे दोबारा अपलोड नहीं करती।
रीड-ओनली व्यक्तिगत टोकन clone और pull कर सकता है, हालाँकि डाउनलोड सूची का अनुरोध एक POST है। यह push या लॉक नहीं कर सकता। मिरर और रीड गेटवे को मिरर और रीड गेटवे में समझाया गया है।
ट्रांसफ़र कैसे होता है
रोज़ के काम के लिए आपको इन विवरणों की ज़रूरत नहीं है। जब आप प्रॉक्सी या फ़ायरवॉल डीबग करते हैं तो ये मदद करते हैं।
- Git LFS एक
POST /lfs/<repository>/objects/batchभेजता है जिसमें ऑपरेशन (downloadयाupload) और ऑब्जेक्ट की सूची होती है। प्रति अनुरोध 1000 ऑब्जेक्ट तक। Git LFS डिफ़ॉल्ट रूप से अधिकतम 100 भेजता है। - Arkvory हर उस ऑब्जेक्ट के लिए लिंक के साथ उत्तर देता है जिसे स्थानांतरित करना है, जो एक घंटे के लिए मान्य होता है। अपलोड के लिए वह उन ऑब्जेक्ट को छोड़ देता है जो उसके पास पहले से हैं।
- Git LFS हर ऑब्जेक्ट को
PUTसे भेजता है, याGETसे डाउनलोड करता है,/lfs/<repository>/objects/<oid>पर। अनुरोध में बैच अनुरोध जैसी ही कुंजी होती है। PUTकोContent-Lengthहेडर चाहिए। chunked अपलोड422के साथ अस्वीकार कर दिया जाता है।
समर्थित:
| मद | मान |
|---|---|
| ट्रांसफ़र अडैप्टर | केवल basic |
| हैश एल्गोरिद्म | केवल sha256। दूसरा माँगने वाले क्लाइंट को 409 मिलता है। |
| प्रमाणीकरण | Basic (कुंजी पासवर्ड के रूप में) या Bearer |
| डाउनलोड | Range अनुरोधों के साथ GET और HEAD |
| मीडिया प्रकार | JSON अनुरोधों के लिए application/vnd.git-lfs+json। किसी भी मीडिया प्रकार के ऑब्जेक्ट बॉडी बाइट के रूप में संग्रहीत होते हैं। |
त्रुटियाँ message और request_id वाले JSON दस्तावेज़ हैं। व्यवस्थापक से सहायता माँगते समय request_id बताएँ।
लिंक उस पते की ओर इंगित करते हैं जिससे क्लाइंट सर्वर तक पहुँचा। जब रिवर्स प्रॉक्सी HTTPS समाप्त करता है, तो उसे Host हेडर पास करना चाहिए और X-Forwarded-Proto: https भेजना चाहिए, जैसा इंस्टॉलेशन के nginx उदाहरण में है, ताकि लिंक https इस्तेमाल करें। Arkvory कुंजी को लिंक में केवल तब डालता है जब लिंक https हो या स्थानीय कंप्यूटर की ओर इंगित करता हो। किसी दूसरे होस्ट पर सादे HTTP पर, git ऑब्जेक्ट के साथ कुंजी नहीं भेज सकता और ट्रांसफ़र विफल हो जाता है।
बड़ी फ़ाइलें और जारी रखना
- Git LFS हर ऑब्जेक्ट एक
PUTअनुरोध में भेजता है। विफलता के बाद वह ऑब्जेक्ट को पहले बाइट से फिर शुरू करता है।tusअडैप्टर, जो ऑब्जेक्ट के भीतर जारी रखता है, समर्थित नहीं है। - अपलोड अनुरोध 30 मिनट के भीतर पूरा होना चाहिए और 30 सेकंड से अधिक रुकना नहीं चाहिए (
ARKVORY_UPLOAD_DEADLINE_MS,ARKVORY_UPLOAD_IDLE_TIMEOUT_MS)। कई गीगाबाइट की फ़ाइल को तेज़ और स्थिर नेटवर्क चाहिए। बड़ी फ़ाइलों के लिएarkvoryctlइस्तेमाल करें, जो भागों में अपलोड करता है। - डाउनलोड
Rangeअनुरोध स्वीकार करते हैं। - एक ऑब्जेक्ट इंस्टॉलेशन के अधिकतम ऑब्जेक्ट आकार जितना बड़ा हो सकता है (
ARKVORY_MAX_OBJECT_BYTES, डिफ़ॉल्ट रूप से लगभग 10 TiB)। बड़ा ऑब्जेक्ट बैच उत्तर में422के साथ अस्वीकार कर दिया जाता है।
डिफ़ॉल्ट रूप से सर्वर एक साथ 2 अपलोड और प्रति कुंजी 1 चलाता है (ARKVORY_MAX_UPLOADS, ARKVORY_MAX_UPLOADS_PER_PRINCIPAL)। Git LFS डिफ़ॉल्ट रूप से एक साथ 8 ऑब्जेक्ट भेजता है। बाकी अपलोड खाली स्लॉट की प्रतीक्षा करते हैं और 20 सेकंड के बाद 503 के साथ हार मान लेते हैं (ARKVORY_TRANSFER_QUEUE_TIMEOUT_MS)। Git LFS विफल ऑब्जेक्ट को कुछ बार दोहराता है, लेकिन बड़ी फ़ाइलों का push कम समानांतर ट्रांसफ़र के साथ अधिक भरोसेमंद होता है:
git config lfs.concurrenttransfers 1आप व्यवस्थापक से सीमाएँ बढ़ाने के लिए भी कह सकते हैं। वे एनवायरनमेंट वेरिएबल में वर्णित हैं।
मिरर और रीड गेटवे
| स्थान | clone और fetch | push और लॉक |
|---|---|---|
| मुख्य सर्वर | हाँ | हाँ |
| मिरर | हाँ। मिरर के पास अपने स्रोत के ऑब्जेक्ट हैं, इसलिए lfs.url उसकी ओर इंगित करें। | अस्वीकृत (409, कारण mirror_read_only)। लॉक मिरर पर कॉपी नहीं किए जाते। |
| रीड गेटवे | नहीं। डाउनलोड सूची एक POST अनुरोध है, जिसे रीड गेटवे स्वीकार नहीं करता। | नहीं |
lfs.url को हमेशा मुख्य सर्वर की ओर, या रीड-ओनली मशीनों के लिए मिरर की ओर इंगित करें।
समस्या निवारण
| संदेश या लक्षण | कारण | क्या करें |
|---|---|---|
401 या प्रमाणीकरण त्रुटि | कुंजी नहीं, गलत कुंजी, या समाप्त या निरस्त टोकन | अपने क्रेडेंशियल मैनेजर में सहेजा क्रेडेंशियल हटाएँ और मान्य कुंजी के साथ फिर से push करें |
403 "Read-only personal access token" के साथ | टोकन में read स्कोप है | read-write स्कोप वाला टोकन बनाएँ |
403 | कुंजी में इस ऑपरेशन के लिए एक्सेस नहीं है, या रिपॉज़िटरी उसे नहीं दी गई है | अनुमतियाँ से कार्रवाइयाँ जोड़ें |
Lock failed: already created lock | किसी के पास लॉक है | स्वामी से अनलॉक करने के लिए कहें, या व्यवस्थापक से --force इस्तेमाल करने को कहें |
422 "Object exceeds the maximum size" | ऑब्जेक्ट इंस्टॉलेशन की सीमा से बड़ा है | ऐसी फ़ाइलों के लिए arkvoryctl इस्तेमाल करें |
अपलोड पर 422 | सामग्री oid से मेल नहीं खाती; push के दौरान फ़ाइल बदल गई | git lfs push फिर से चलाएँ |
503 या Retry-After | एक साथ बहुत अधिक ट्रांसफ़र | lfs.concurrenttransfers घटाएँ और फिर प्रयास करें |
507 | रिपॉज़िटरी कोटा या इंस्टॉलेशन की क्षमता भर गई है | जगह खाली करें या बड़ा कोटा माँगें |
अपलोड पर 409 | रिपॉज़िटरी एक मिरर है | मुख्य सर्वर पर push करें |
वर्किंग ट्री में फ़ाइलें oid वाली छोटी टेक्स्ट फ़ाइलें हैं | ऑब्जेक्ट डाउनलोड नहीं हुए, या git lfs install नहीं चलाया गया | git lfs install, फिर git lfs pull चलाएँ |
x509: certificate signed by unknown authority | क्लाइंट प्रमाणपत्र पर भरोसा नहीं करता | सर्टिफ़िकेट प्राधिकरण को सिस्टम के ट्रस्ट स्टोर में जोड़ें, या http.sslCAInfo सेट करें |
TLS सत्यापन बंद न करें (GIT_SSL_NO_VERIFY): हर अनुरोध के साथ कुंजी भेजी जाती है।