# Въведение в GitHub Този урок обхваща основите на GitHub, платформа за хостване и управление на промените във вашия код.  > Скетч от [Tomomi Imura](https://twitter.com/girlie_mac) ## Предварителен тест [Предварителен тест](https://ff-quizzes.netlify.app) ## Въведение В този урок ще разгледаме: - проследяване на работата, която вършите на вашия компютър - работа по проекти с други хора - как да допринасяте за софтуер с отворен код ### Предварителни изисквания Преди да започнете, трябва да проверите дали Git е инсталиран. В терминала напишете: `git --version` Ако Git не е инсталиран, [изтеглете Git](https://git-scm.com/downloads). След това настройте вашия локален Git профил в терминала: * `git config --global user.name "вашето-име"` * `git config --global user.email "вашият-имейл"` За да проверите дали Git вече е конфигуриран, можете да напишете: `git config --list` Ще ви е необходим и акаунт в GitHub, редактор за код (като Visual Studio Code) и трябва да отворите вашия терминал (или команден ред). Отидете на [github.com](https://github.com/) и създайте акаунт, ако все още нямате такъв, или влезте и попълнете вашия профил. ✅ GitHub не е единственото хранилище за код в света; има и други, но GitHub е най-известното. ### Подготовка Ще ви е необходима папка с проект на код на вашия локален компютър (лаптоп или PC) и публично хранилище в GitHub, което ще служи като пример за това как да допринасяте за проектите на други хора. --- ## Управление на код Да кажем, че имате локална папка с проект на код и искате да започнете да проследявате вашия напредък с помощта на git - системата за контрол на версиите. Някои хора сравняват използването на git с писане на любовно писмо до вашето бъдещо аз. Четейки вашите съобщения за комит дни, седмици или месеци по-късно, ще можете да си припомните защо сте взели дадено решение или да "върнете" промяна - стига да пишете добри "съобщения за комит". ### Задача: Създайте хранилище и комитнете код > Вижте видеото > > [](https://www.youtube.com/watch?v=9R31OUPpxU4) 1. **Създайте хранилище в GitHub**. На GitHub.com, в раздела за хранилища или от навигационната лента горе вдясно, намерете бутона **new repo**. 1. Дайте име на вашето хранилище (папка). 1. Изберете **create repository**. 1. **Навигирайте до вашата работна папка**. В терминала преминете към папката (известна още като директория), която искате да започнете да проследявате. Напишете: ```bash cd [name of your folder] ``` 1. **Инициализирайте git хранилище**. Във вашия проект напишете: ```bash git init ``` 1. **Проверете статуса**. За да проверите статуса на вашето хранилище, напишете: ```bash git status ``` резултатът може да изглежда така: ```output Changes not staged for commit: (use "git add ..." to update what will be committed) (use "git checkout -- ..." to discard changes in working directory) modified: file.txt modified: file2.txt ``` Обикновено командата `git status` ви казва неща като кои файлове са готови за _запазване_ в хранилището или имат промени, които може да искате да запазите. 1. **Добавете всички файлове за проследяване** Това също се нарича поставяне на файлове/ добавяне на файлове в зоната за поставяне. ```bash git add . ``` Аргументът `git add` плюс `.` показва, че всички ваши файлове и промени са готови за проследяване. 1. **Добавете избрани файлове за проследяване** ```bash git add [file or folder name] ``` Това ни помага да добавим само избрани файлове в зоната за поставяне, когато не искаме да комитнем всички файлове наведнъж. 1. **Премахнете всички файлове от зоната за поставяне** ```bash git reset ``` Тази команда ни помага да премахнем всички файлове от зоната за поставяне наведнъж. 1. **Премахнете конкретен файл от зоната за поставяне** ```bash git reset [file or folder name] ``` Тази команда ни помага да премахнем само конкретен файл от зоната за поставяне, който не искаме да включим в следващия комит. 1. **Запазване на вашата работа**. На този етап сте добавили файловете в така наречената _зона за поставяне_. Място, където Git проследява вашите файлове. За да направите промяната постоянна, трябва да _комитнете_ файловете. За да направите това, създавате _комит_ с командата `git commit`. _Комит_ представлява точка за запазване в историята на вашето хранилище. Напишете следното, за да създадете _комит_: ```bash git commit -m "first commit" ``` Това комитва всички ваши файлове, добавяйки съобщението "first commit". За бъдещи съобщения за комит ще искате да бъдете по-описателни, за да предадете какъв тип промяна сте направили. 1. **Свържете вашето локално Git хранилище с GitHub**. Git хранилище е полезно на вашия компютър, но в даден момент ще искате да имате резервно копие на вашите файлове някъде и също така да поканите други хора да работят с вас върху вашето хранилище. Едно такова чудесно място за това е GitHub. Помнете, че вече сме създали хранилище в GitHub, така че единственото, което трябва да направим, е да свържем нашето локално Git хранилище с GitHub. Командата `git remote add` ще направи точно това. Напишете следната команда: > Забележка: преди да напишете командата, отидете на страницата на вашето GitHub хранилище, за да намерите URL адреса на хранилището. Ще го използвате в командата по-долу. Заменете ```https://github.com/username/repository_name.git``` с вашия GitHub URL. ```bash git remote add origin https://github.com/username/repository_name.git ``` Това създава _remote_, или връзка, наречена "origin", сочеща към GitHub хранилището, което създадохте по-рано. 1. **Изпратете локалните файлове в GitHub**. Досега сте създали _връзка_ между локалното хранилище и GitHub хранилището. Нека изпратим тези файлове в GitHub със следната команда `git push`, както следва: > Забележка: името на вашия клон може да е различно по подразбиране от ```main```. ```bash git push -u origin main ``` Това изпраща вашите комити в клона "main" в GitHub. Задаването на `upstream` клон, включително `-u` в командата, установява връзка между вашия локален клон и отдалечения клон, така че можете просто да използвате git push или git pull, без да посочвате името на клона в бъдеще. Git автоматично ще използва upstream клона и няма да е необходимо да посочвате името на клона изрично в бъдещи команди. 2. **Добавяне на още промени**. Ако искате да продължите да правите промени и да ги изпращате в GitHub, просто ще трябва да използвате следните три команди: ```bash git add . git commit -m "type your commit message here" git push ``` > Съвет: Може също да искате да използвате файл `.gitignore`, за да предотвратите появата на файлове, които не искате да проследявате, в GitHub - като например файл с бележки, който съхранявате в същата папка, но няма място в публично хранилище. Можете да намерите шаблони за файлове `.gitignore` на [.gitignore templates](https://github.com/github/gitignore). #### Съобщения за комит Добро заглавие на съобщение за Git комит завършва следното изречение: Ако бъде приложено, този комит ще <вашето заглавие тук> За заглавието използвайте императивно настояще време: "промени" вместо "променено" или "промени". Както в заглавието, така и в тялото (по избор) използвайте императивно настояще време. Тялото трябва да включва мотивацията за промяната и да я сравни с предишното поведение. Обяснявате `защо`, а не `как`. ✅ Отделете няколко минути, за да разгледате GitHub. Можете ли да намерите наистина добро съобщение за комит? Можете ли да намерите наистина минимално? Каква информация според вас е най-важна и полезна за предаване в съобщение за комит? ### Задача: Сътрудничество Основната причина за качването на неща в GitHub беше да се направи възможно сътрудничеството с други разработчици. ## Работа по проекти с други хора > Вижте видеото > > [](https://www.youtube.com/watch?v=bFCM-PC3cu8) Във вашето хранилище навигирайте до `Insights > Community`, за да видите как вашият проект се сравнява с препоръчаните стандарти за общността. Ето някои неща, които могат да подобрят вашето GitHub хранилище: - **Описание**. Добавихте ли описание за вашия проект? - **README**. Добавихте ли README? GitHub предоставя насоки за писане на [README](https://docs.github.com/articles/about-readmes/?WT.mc_id=academic-77807-sagibbon). - **Насоки за допринасяне**. Има ли вашият проект [насоки за допринасяне](https://docs.github.com/articles/setting-guidelines-for-repository-contributors/?WT.mc_id=academic-77807-sagibbon)? - **Кодекс на поведение**. [Кодекс на поведение](https://docs.github.com/articles/adding-a-code-of-conduct-to-your-project/). - **Лиценз**. Може би най-важното, [лиценз](https://docs.github.com/articles/adding-a-license-to-a-repository/)? Всички тези ресурси ще бъдат от полза за въвеждането на нови членове на екипа. Това са типично нещата, които новите сътрудници разглеждат, преди дори да погледнат вашия код, за да разберат дали вашият проект е правилното място за тях да прекарват времето си. ✅ README файловете, въпреки че отнемат време за подготовка, често се пренебрегват от заети поддържатели. Можете ли да намерите пример за особено описателен README? Забележка: има някои [инструменти за създаване на добри README файлове](https://www.makeareadme.com/), които може да искате да опитате. ### Задача: Слейте код Документите за допринасяне помагат на хората да допринасят за проекта. Те обясняват какви типове допринасяния търсите и как работи процесът. Сътрудниците ще трябва да преминат през серия от стъпки, за да могат да допринасят за вашето хранилище в GitHub: 1. **Форкване на вашето хранилище**. Вероятно ще искате хората да _форкнат_ вашия проект. Форкването означава създаване на реплика на вашето хранилище в техния GitHub профил. 1. **Клониране**. Оттам те ще клонират проекта на своя локален компютър. 1. **Създаване на клон**. Ще искате да ги помолите да създадат _клон_ за своята работа. 1. **Фокусиране на промяната върху една област**. Помолете сътрудниците да концентрират своите допринасяния върху едно нещо наведнъж - така шансовете да можете да _слеете_ тяхната работа са по-високи. Представете си, че те пишат поправка на бъг, добавят нова функция и актуализират няколко теста - какво ако искате или можете да приложите само 2 от 3, или 1 от 3 промени? ✅ Представете си ситуация, в която клоновете са особено критични за писането и доставянето на добър код. Какви случаи на употреба можете да си представите? > Забележка: бъдете промяната, която искате да видите в света, и създавайте клонове за вашата собствена работа също. Всички комити, които правите, ще бъдат направени в клона, в който сте "преминали". Използвайте `git status`, за да видите кой клон е това. Нека преминем през работния процес на сътрудник. Да предположим, че сътрудникът вече е _форкнал_ и _клонирал_ хранилището, така че има готово Git хранилище за работа на своя локален компютър: 1. **Създаване на клон**. Използвайте командата `git branch`, за да създадете клон, който ще съдържа промените, които възнамеряват да допринесат: ```bash git branch [branch-name] ``` 1. **Превключване към работния клон**. Превключете към посочения клон и актуализирайте работната директория с `git switch`: ```bash git switch [branch-name] ``` 1. **Работа**. На този етап искате да добавите вашите промени. Не забравяйте да уведомите Git за това със следните команди: ```bash git add . git commit -m "my changes" ``` Уверете се, че давате на вашия комит добро име, за ваше удобство, както и за поддържателя на хранилището, на което помагате. 1. **Сливане на вашата работа с клона `main`**. В даден момент сте готови с работата си и искате да я слеете с тази на клона `main`. Междувременно клонът `main` може да се е променил, така че се уверете, че първо го актуализирате до последната версия със следните команди: ```bash git switch main git pull ``` На този етап искате да се уверите, че всички _конфликти_, ситуации, в които Git не може лесно да _слее_ промените, се случват във вашия работен клон. Затова изпълнете следните команди: ```bash git switch [branch_name] git merge main ``` Командата `git merge main` ще внесе всички промени от `main` във вашия клон. Надяваме се, че можете просто да продължите. Ако не, VS Code ще ви покаже къде Git е _объркан_ и просто променяте засегнатите файлове, за да посочите кое съдържание е най-точно. За да превключите към различен клон, използвайте модерната команда `git switch`: ```bash git switch [branch_name] 1. **Изпратете вашата работа в GitHub**. Изпращането на вашата работа в GitHub означава две неща. Пушване на вашия клон във вашето хранилище и след това отваряне на PR, Pull Request. ```bash git push --set-upstream origin [branch-name] ``` Горната команда създава клона във вашето форкнато хранилище. 1. **Отворете PR**. Следващата стъпка е да отворите PR. Това става, като отидете в клонираното хранилище в GitHub. Ще видите индикация в GitHub, която пита дали искате да създадете нов PR. Кликнете върху това и ще бъдете пренасочени към интерфейс, където можете да промените заглавието на съобщението за комит и да добавите по-подходящо описание. Сега поддържащият на хранилището, което сте клонирали, ще види този PR и _да се надяваме_ ще го оцени и _обедини_ вашия PR. Вече сте сътрудник, ура :) 1. **Почистване**. Счита се за добра практика да _почистите_, след като успешно обедините PR. Трябва да почистите както локалния си клон, така и клона, който сте качили в GitHub. Първо, нека го изтрием локално със следната команда: ```bash git branch -d [branch-name] ``` Уверете се, че сте отишли на страницата на клонираното хранилище в GitHub и сте премахнали отдалечения клон, който току-що сте качили. `Pull request` може да изглежда като странен термин, защото всъщност искате да качите промените си в проекта. Но поддържащият (собственикът на проекта) или основният екип трябва да разгледа вашите промени, преди да ги обедини с "главния" клон на проекта, така че всъщност искате решение за промяна от поддържащия. Pull request е мястото, където можете да сравнявате и обсъждате разликите, въведени в клона, с ревюта, коментари, интегрирани тестове и други. Един добър pull request следва приблизително същите правила като съобщението за комит. Можете да добавите препратка към проблем в тракера за проблеми, например когато вашата работа решава даден проблем. Това се прави с `#`, последвано от номера на проблема. Например `#97`. 🤞Да се надяваме, че всички проверки ще преминат успешно и собственикът(ите) на проекта ще обединят вашите промени в проекта🤞 Актуализирайте текущия локален работен клон с всички нови комити от съответния отдалечен клон в GitHub: `git pull` ## Как да допринасяте към отворен код Първо, нека намерим хранилище (или **repo**) в GitHub, което ви интересува и към което искате да допринесете с промяна. Ще трябва да копирате съдържанието му на вашата машина. ✅ Добър начин да намерите хранилища, подходящи за начинаещи, е да [търсите по етикета 'good-first-issue'](https://github.blog/2020-01-22-browse-good-first-issues-to-start-contributing-to-open-source/).  Има няколко начина за копиране на код. Един от тях е да "клонирате" съдържанието на хранилището, използвайки HTTPS, SSH или GitHub CLI (Command Line Interface). Отворете терминала си и клонирайте хранилището по следния начин: `git clone https://github.com/ProjectURL` За да работите по проекта, преминете към правилната папка: `cd ProjectURL` Можете също така да отворите целия проект, използвайки [Codespaces](https://github.com/features/codespaces), вградения редактор на код / облачна среда за разработка на GitHub, или [GitHub Desktop](https://desktop.github.com/). Накрая, можете да изтеглите кода в компресиран папка. ### Няколко интересни неща за GitHub Можете да добавите звезда, да следите и/или да "клонирате" всяко публично хранилище в GitHub. Можете да намерите вашите хранилища със звезда в падащото меню в горния десен ъгъл. Това е като отметка, но за код. Проектите имат тракер за проблеми, най-често в GitHub в раздела "Issues", освен ако не е посочено друго, където хората обсъждат проблеми, свързани с проекта. А разделът Pull Requests е мястото, където хората обсъждат и преглеждат промени, които са в процес на работа. Проектите може също да имат дискусии във форуми, пощенски списъци или чат канали като Slack, Discord или IRC. ✅ Разгледайте новото си хранилище в GitHub и опитайте няколко неща, като редактиране на настройки, добавяне на информация към хранилището и създаване на проект (като Канбан дъска). Има много неща, които можете да направите! --- ## 🚀 Предизвикателство Работете в екип с приятел върху кода на другия. Създайте проект съвместно, клонирайте код, създайте клонове и обединете промени. ## Тест след лекцията [Тест след лекцията](https://ff-quizzes.netlify.app/web/en/) ## Преглед и самостоятелно обучение Прочетете повече за [допринасянето към софтуер с отворен код](https://opensource.guide/how-to-contribute/#how-to-submit-a-contribution). [Git cheatsheet](https://training.github.com/downloads/github-git-cheat-sheet/). Практикувайте, практикувайте, практикувайте. GitHub предлага страхотни учебни пътеки чрез [skills.github.com](https://skills.github.com): - [Първата седмица в GitHub](https://skills.github.com/#first-week-on-github) Ще намерите и по-напреднали курсове. ## Задача Завършете [курса "Първата седмица в GitHub"](https://skills.github.com/#first-week-on-github) --- **Отказ от отговорност**: Този документ е преведен с помощта на AI услуга за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за недоразумения или погрешни интерпретации, произтичащи от използването на този превод.