Branches and Merging: Working on Many Things at Onceلقەکان و بەیەککردن: کارکردن لەسەر چەند شتێک لە یەک کاتدا

Bazaar Cart works, and two jobs arrive at once (prices in this lesson are made up, in IQD). Karwan must add the delivery fee, rule R4; it will take him a day or two. Meanwhile Dilan, the tester, finds a bug: honey costs 30,000 IQD per kilogram, but prices.py says 3000 — a zero has been missing since the very first commit. Shilan must fix it today. Neither job may break main, the code Soran's shop uses every day.

Bazaar Cart کار دەکات و دوو کار پێکەوە دێن (نرخەکانی ئەم وانەیە دەستکردن و بە دینارن). کاروان دەبێت کرێی گەیاندن زیاد بکات، ڕێسای ⁦R4⁩؛ ڕۆژێک یان دوو ڕۆژی پێدەچێت. لەو کاتەدا دیلان، تاقیکەرەوەی نەرمەواڵە (Software tester)، باگێک دەدۆزێتەوە: هەنگوین کیلۆی بە ⁦30,000⁩ دینارە، بەڵام prices.py دەڵێت 3000 — سفرێک لە یەکەم کۆمیتەوە ونە. شیلان دەبێت ئەمڕۆ چاکی بکات. هیچ کامیان نابێت main تێک بدەن، ئەو کۆدەی دوکانەکەی سۆران هەموو ڕۆژێک بەکاری دەهێنێت.

The answer is branches: separate lines of work inside one repository. Each person works on their own branch; when the work is ready and checked, it is merged back into main.

وەڵامەکە لقەکانن: هێڵی جیای کار لە ناو یەک کۆگای کۆددا (Repository). هەر کەسێک لەسەر لقی خۆی کار دەکات؛ کاتێک کارەکە ئامادە و پشکنراو بوو، دەگەڕێتەوە ناو main (بەیەککردن).

Remember that every commit points to its parent (Git basics). A branch is simply a name that points to one commit — in Git it is a tiny file of 41 bytes holding a commit hash, so making one is instant and copies nothing. main is an ordinary branch that git init -b main made. When you commit, the branch you are on moves forward to the new commit.

لەبیرت بێت هەر کۆمیتێک ئاماژە بە دایکەکەی دەکات (بنەماکانی Git). لق تەنیا ناوێکە کە ئاماژە بە یەک کۆمیت دەکات — لە Gitـدا فایلێکی (File) بچکۆلەیە بە قەبارەی ⁦41⁩ بایت (Byte) کە هاشی کۆمیتێک (Commit hash) هەڵدەگرێت، بۆیە دروستکردنی یەکسەرییە و هیچ شتێک کۆپی ناکات. main لقێکی ئاساییە کە git init -b main دروستی کرد. کاتێک کۆمیت دەکەیت، ئەو لقەی لەسەریتی دەچێتە پێش بۆ کۆمیتە نوێیەکە.

HEAD is Git's marker for where you are: it points to your current branch. git branch lists the branches and marks HEAD's branch with *; git branch <name> makes a new branch but does not switch to it.

HEAD نیشانەی Gitـە بۆ ئێستا لە کوێیت: ئاماژە بە لقی ئێستات دەکات. git branch لقەکان لیست دەکات و لقی HEAD بە * نیشان دەکات؛ git branch <name> لقێکی نوێ دروست دەکات بەڵام ناتباتە سەری.

git switch -c feature/delivery-fee creates the branch and switches to it (-c = create; older tutorials write git checkout -b). Karwan adds one line, DELIVERY_FEE = 2500 — Soran's price at that time — and commits:

git switch -c feature/delivery-fee لقەکە دروست دەکات و دەچێتە سەری (-c = create؛ فێرکارییە کۆنەکان git checkout -b دەنووسن). کاروان یەک دێڕ زیاد دەکات، DELIVERY_FEE = 2500 — نرخی سۆران لەو کاتەدا — و کۆمیت دەکات:

Karwan has started writing delivery_fee() but has not committed it. Now Shilan needs main. Switching would replace prices.py with main's version and destroy his edit, so Git refuses:

کاروان دەستی کردووە بە نووسینی delivery_fee() بەڵام هێشتا کۆمیتی نەکردووە. ئێستا شیلان پێویستی بە main هەیە. گواستنەوە prices.py بە وەشانەکەی main دەگۆڕێت و دەستکارییەکەی لەناو دەبات، بۆیە Git ڕەتی دەکاتەوە:

Two ways out. Usually simplest: commit the unfinished work on the branch (you can improve it in later commits). For a short break there is git stash: it puts your uncommitted changes in a drawer and makes the working tree clean; later, on the same branch, git stash pop brings them back:

دوو ڕێگە هەیە. زۆرجار سادەترینیان: کارە تەواونەکراوەکە لەسەر لقەکە کۆمیت بکە (دەتوانیت لە کۆمیتەکانی دواتردا باشتری بکەیت). بۆ پشوویەکی کورت git stash هەیە: گۆڕانکارییە کۆمیتنەکراوەکانت دەخاتە چەکمەجەیەکەوە و فۆڵدەری کار (Working tree) پاک دەکاتەوە؛ دواتر، لەسەر هەمان لق، git stash pop دەیانگەڕێنێتەوە:

Shilan makes her own branch from main, fixes the honey price and commits. Then she switches back to main and merges her branch into it — git merge always brings the named branch into the branch you are on:

شیلان لقی خۆی لە main دروست دەکات، نرخی هەنگوین چاک دەکات و کۆمیت دەکات. پاشان دەگەڕێتەوە سەر main و لقەکەی خۆی تێکەڵی دەکات — git merge هەمیشە ئەو لقەی ناوی دەبەیت دەهێنێتە ناو ئەو لقەی لەسەریتی:

Nothing new had happened on main since Shilan's branch started, so there was nothing to combine. Git only moved the name main forward to her commit: a fast-forward merge. No new commit is made, and the history stays one straight line.

لەو کاتەوەی لقەکەی شیلان دەستی پێکرد، هیچ شتێکی نوێ لەسەر main ڕووی نەدابوو، بۆیە هیچ شتێک نەبوو تا پێکەوە ببەسترێت. Git تەنیا ناوی mainـی بۆ کۆمیتەکەی ئەو برد: بەیەککردنی بەپێشخستن. هیچ کۆمیتێکی نوێ دروست ناکرێت و مێژووەکە وەک هێڵێکی ڕاست دەمێنێتەوە.

Karwan goes back to his branch, takes his work out of the stash and finishes it: delivery_fee() in prices.py and a delivery line in cart.py:

کاروان دەگەڕێتەوە سەر لقەکەی، کارەکەی لە stash دەردەهێنێت و تەواوی دەکات: delivery_fee() لە prices.py و دێڕێکی گەیاندن لە cart.py:

Now main has a commit his branch does not have (Shilan's fix), and his branch has two commits main does not have: the two lines of work have diverged. Git compares three snapshots — the common ancestor and the two branch tips — joins both sets of changes and records the result in a merge commit with two parents:

ئێستا main کۆمیتێکی هەیە کە لقەکەی ئەو نییەتی (چاککردنەکەی شیلان) و لقەکەی ئەویش دوو کۆمیتی هەیە کە main نییەتی: هەردوو هێڵی کارەکە لێک جیا بوونەتەوە. Git سێ وێنەی تەواو بەراورد دەکات — کۆمیتە هاوبەشەکەی پێشوو و دوایین کۆمیتی هەردوو لقەکە — هەردوو کۆمەڵە گۆڕانکارییەکە پێکەوە دەبەستێت و ئەنجامەکە لە کۆمیتێکی بەیەککردندا بە دوو دایک تۆمار دەکات:

Here is everything so far, first as an animation, then as Git draws it in text. Read the text graph from the bottom up: each * is a commit, |/ is where a branch started, and the * where two lines meet again is a merge commit.

ئەمە هەموو ئەوەیە کە تا ئێستا ڕوویدا، سەرەتا وەک ئەنیمەیشن، پاشان وەک ئەوەی Git بە دەق دەیکێشێت. گرافە دەقییەکە لە خوارەوە بۆ سەرەوە بخوێنەرەوە: هەر *ـێک کۆمیتێکە، |/ ئەو شوێنەیە کە لقێک دەستی پێکرد و ئەو *ـەی دوو هێڵ تێیدا دیسان دەگەنەوە یەک کۆمیتی بەیەککردنە.

Most merges are automatic. A merge conflict happens only when both branches changed the same lines of a file in different ways: Git cannot know which is right, so it stops and asks a person. The next day Soran phones: fuel is dearer, delivery is now 3,000 IQD. Shilan changes DELIVERY_FEE = 2500 to 3000 on fix/delivery-fee. At the same time Karwan, on feature/free-delivery, adds the rest of R4 — free delivery from 50,000 IQD of goods — and adds a comment on the same line. Shilan's branch is merged first (a fast-forward). Then Karwan's:

زۆربەی بەیەککردنەکان خۆکارن. ناکۆکیی بەیەککردن تەنیا کاتێک ڕوو دەدات کە هەردوو لقەکە هەمان دێڕەکانی فایلێک بە دوو شێوەی جیاواز گۆڕیبن: Git نازانێت کامیان ڕاستە، بۆیە دەوەستێت و پرسیار لە کەسێک دەکات. ڕۆژی دواتر سۆران تەلەفۆن دەکات: سووتەمەنی گرانتر بووە، گەیاندن ئێستا ⁦3,000⁩ دینارە. شیلان لەسەر fix/delivery-fee، DELIVERY_FEE = 2500 دەگۆڕێت بۆ 3000. لە هەمان کاتدا کاروان، لەسەر feature/free-delivery، بەشەکەی تری ⁦R4⁩ زیاد دەکات — گەیاندنی بێبەرانبەر لە ⁦50,000⁩ دینار کاڵا بەرەو سەرەوە — و لێدوانێک (Comment) لەسەر هەمان دێڕ زیاد دەکات. سەرەتا لقەکەی شیلان تێکەڵ دەکرێت (بەیەککردنی بەپێشخستن). پاشان هی کاروان:

Git writes both versions into prices.py, between conflict markers. Everything between <<<<<<< HEAD and ======= is your side (the branch you are on, main); everything between ======= and >>>>>>> is the incoming branch:

Git هەردوو وەشانەکە لە ناو prices.pyـدا دەنووسێت، لە نێوان نیشانەکانی ناکۆکیدا. هەموو ئەوەی لە نێوان <<<<<<< HEAD و =======ـدایە لای خۆتە (ئەو لقەی لەسەریتی، main)؛ هەموو ئەوەی لە نێوان ======= و >>>>>>>ـدایە لقە هاتووەکەیە:

Changed your mind? git merge --abort puts everything back as it was before the merge.

پەشیمان بوویتەوە؟ git merge --abort هەموو شتێک دەگەڕێنێتەوە بۆ ئەوەی پێش بەیەککردنەکە بوو.

Editors help: VS Code marks each conflict with Accept Current Change, Accept Incoming Change, Accept Both Changes and Compare Changes, and has a three-way merge editor. Here Accept Both would keep two DELIVERY_FEE lines — the buttons save typing, but you still decide.

دەستکاریکەرەکان یارمەتی دەدەن: VS Code هەر ناکۆکییەک بە Accept Current Change، Accept Incoming Change، Accept Both Changes و Compare Changes نیشان دەکات و دەستکاریکەرێکی سێ‌بەشیی بەیەککردنی هەیە. لێرەدا Accept Both دوو دێڕی DELIVERY_FEE دەهێڵێتەوە — دوگمەکان (Button) نووسینت لێ کەم دەکەنەوە، بەڵام هێشتا تۆ بڕیار دەدەیت.

If you run the program while the markers are still in the file — or, worse, commit them — Python stops at once: <<<<<<< is not Python. This is what Karwan saw when he tried cart.py in the middle of the conflict:

ئەگەر بەرنامەکە (Program) جێبەجێ بکەیت لە کاتێکدا نیشانەکان هێشتا لە فایلەکەدان — یان خراپتر، کۆمیتیان بکەیت — Python یەکسەر دەوەستێت: <<<<<<< Python نییە. ئەمە ئەوە بوو کە کاروان بینی کاتێک لە ناوەڕاستی ناکۆکییەکەدا cart.pyـی تاقی کردەوە:

The traceback points to prices.py, line 12: the <<<<<<< HEAD line (reading a traceback, syntax errors). Before git add, let Git look for you: git diff --check lists every leftover marker.

ڕێچکەی هەڵەکە (Traceback) ئاماژە بە prices.py دەکات، دێڕی ⁦12⁩: دێڕی <<<<<<< HEAD (خوێندنەوەی ڕێچکەی هەڵە، هەڵەکانی داڕستن). پێش git add، با Git بۆت بگەڕێت: git diff --check هەموو نیشانەیەکی بەجێماو لیست دەکات.

Conflicts are normal in a team, not a disaster. But each one costs time, and the longer two lines of work stay apart, the more they differ. Habits that keep conflicts small:

ناکۆکی لە تیمێکدا شتێکی ئاساییە، کارەسات نییە. بەڵام هەریەکەیان کاتی دەوێت و هەتا دوو هێڵی کار زیاتر لێک دوور بمێننەوە، زیاتر لێک جیاواز دەبن. خووەکان کە ناکۆکییەکان بچووک دەهێڵنەوە:

A merged branch has done its job. git branch --merged lists the branches whose commits are all in the current branch, and git branch -d deletes them. Only the names go; the commits stay in main's history.

لقێکی تێکەڵکراو کاری خۆی کردووە. git branch --merged ئەو لقانە لیست دەکات کە هەموو کۆمیتەکانیان لە لقی ئێستادان و git branch -d دەیانسڕێتەوە. تەنیا ناوەکان دەڕۆن؛ کۆمیتەکان لە مێژووی mainـدا دەمێننەوە.

Git protects unmerged work. Karwan tried a 5 % discount on experiment/discount, and Soran said no. -d refuses to delete a branch that is not merged; only -D forces it — and then those commits are lost:

Git کاری تێکەڵنەکراو دەپارێزێت. کاروان داشکاندنی ⁦5%⁩ لەسەر experiment/discount تاقی کردەوە و سۆران گوتی نا. -d ڕەت دەکاتەوە لقێکی تێکەڵنەکراو بسڕێتەوە؛ تەنیا -D بە زۆر دەیسڕێتەوە — و ئەوکات ئەو کۆمیتانە ون دەبن:

Names tell the team what a branch is for: feature/… for new work, fix/… for bug fixes, short, lowercase, words joined with hyphens — feature/free-delivery, fix/honey-price. Some teams add the issue number: fix/12-honey-price.

ناوەکان بە تیمەکە دەڵێن لقێک بۆ چییە: feature/… بۆ کاری نوێ، fix/… بۆ چاککردنی باگەکان، کورت، بە پیتی بچووک، وشەکان بە هێڵی کورت بەستراون — feature/free-delivery، fix/honey-price. هەندێک تیم ژمارەی ئیشووەکەش زیاد دەکەن: fix/12-honey-price.

Bazaar Cart now has all of rule R4 (3,000 IQD inside Sulaimani, free from 50,000 IQD of goods) and the honey fix — a good moment to mark a version. A tag is a name for one commit that, unlike a branch, never moves:

Bazaar Cart ئێستا هەموو ڕێسای ⁦R4⁩ـی تێدایە (⁦3,000⁩ دینار لە ناو سلێمانی، بێبەرانبەر لە ⁦50,000⁩ دینار کاڵا بەرەو سەرەوە) و چاککردنەکەی هەنگوینیش — کاتێکی باشە بۆ نیشانکردنی وەشانێک. تاگی Git ناوێکە بۆ یەک کۆمیت کە بە پێچەوانەی لقەوە هەرگیز ناجووڵێت:

What the numbers in 0.2.0 and 1.0.0 promise, annotated tags (git tag -a) and releases are taught in Versions and builds.

ئەوەی ژمارەکانی ⁦0.2.0⁩ و ⁦1.0.0⁩ بەڵێنی دەدەن، جۆری annotatedـی تاگی Git (git tag -a) و وەشانە بڵاوکراوەکان (Release) لە وەشان و بیلد فێر دەکرێن.

A branching strategy is the team's agreement on how branches are used: when to make one, how long it lives, how it is named and how it gets back into main. Three you will meet:

ستراتیژیی بەکارهێنانی لق ڕێککەوتنی تیمەکەیە لەسەر چۆنیەتیی بەکارهێنانی لقەکان: کەی لقێک دروست دەکرێت، چەند دەژی، چۆن ناو دەنرێت و چۆن دەگەڕێتەوە ناو main. سێ دانەیان دەبینیت:

Bazaar Cart's team of four uses GitHub flow: short branches, a review before every merge, main always ready for Soran's shop. Its six steps on GitHub are shown in GitHub and Teamwork.

تیمە چوار کەسییەکەی Bazaar Cart GitHub flow بەکار دەهێنێت: لقی کورت، پێداچوونەوە پێش هەموو بەیەککردنێک، main هەمیشە ئامادە بۆ دوکانەکەی سۆران. شەش هەنگاوەکەی لەسەر GitHub لە GitHub و کاری تیمی پیشان دراون.