# Руководство пользователя Git для начинающих технических писателей

Добро пожаловать в руководство по Git! Этот документ предназначен для начинающих технических писателей, которые хотят освоить основы системы контроля версий Git. Здесь вы найдете введение в Git, объяснение основных команд, сценарии использования, наиболее распространенные ошибки и информацию о действиях, которые могут привести к необратимым изменениям.

## 1. Введение

### 1.1. Что такое Git для технического писателя

Git — это распределённая система контроля версий, которая позволяет отслеживать изменения в файлах и координировать работу нескольких человек над проектом. Для технического писателя Git может быть полезен для управления документацией, отслеживания изменений и совместной работы с другими авторами и разработчиками.

### 1.2. Зачем использовать Git?

- Отслеживание изменений: Позволяет видеть, кто и когда вносил изменения в документацию.
- История версий: Возможность вернуться к предыдущим версиям документа.
- Совместная работа: Упрощает работу в команде, позволяет нескольким авторам работать над одним проектом.
- Разветвление: Позволяет создавать параллельные ветки разработки документации для новых разделов или исправлений.
- Безопасность данных: Резервное копирование и защита от потери данных.

### 1.3. Основные концепции Git

- Репозиторий: Хранилище проекта, в котором хранятся все файлы и история изменений.
- Коммит (commit): Фиксация изменений в репозитории.
- Ветка (branch): Разделённая версия репозитория, позволяющая работать над разными задачами параллельно.
- Слияние (merge): Объединение изменений из разных веток.
- Клонирование (clone): Создание локальной копии удалённого репозитория.
- Pull request: Запрос на слияние изменений из одной ветки в другую.

---

## 2. Как настроить Git для работы техническому писателю

1. Установка Git:
   - **Windows**: Скачайте установочный файл с официального сайта Git (https://git-scm.com/download/win) и следуйте инструкциям установщика.
   - **macOS**: Вы можете установить Git через Homebrew, выполнив команду `brew install git`, или скачать установочный файл с официального сайта (https://git-scm.com/download/mac).
   - **Linux**: Используйте пакетный менеджер вашей системы. Например, на Ubuntu выполните `sudo apt-get install git`.

2. Настройка имени и электронной почты:
   Эти данные будут использоваться в каждом коммите для идентификации автора.

   ```
   git config --global user.name "Ваше Имя"
   git config --global user.email "ваша_почта@example.com"
   ```

3. Настройка редактора по умолчанию:
   Укажите текстовый редактор, который будет использоваться для редактирования сообщений коммитов по умолчанию.
   ```
   git config --global core.editor "nano"
   ```
   Здесь вы можете заменить nano на любой другой редактор, который предпочитаете (например, vim, code для Visual Studio Code и т.д.).

4. Проверка настроек:
   Чтобы убедиться, что настройки применены, выполните:
   ```
   git config --list
   ```

5. Настройка SSH-ключа (опционально):
   Если вы планируете работать с удаленными репозиториями (например, на GitHub, GitLab), рекомендуется настроить SSH-ключ для аутентификации.
   - Создайте новый SSH-ключ, если у вас его нет:
     ```
     ssh-keygen -t ed25519 -C "ваша_почта@example.com"
     ```
     Следуйте инструкциям на экране. По умолчанию ключ будет создан в ~/.ssh/id_ed25519.
   - Добавьте SSH-ключ в ssh-agent:
     ```
     eval "$(ssh-agent -s)"
     ssh-add ~/.ssh/id_ed25519
     ```
   - Скопируйте содержимое публичного ключа (например, ~/.ssh/id_ed25519.pub) и добавьте его в настройки вашего аккаунта на GitHub, GitLab и т.д.

6. Создание или клонирование репозитория:
   - Создать новый репозиторий:
     ```
     mkdir my_project
     cd my_project
     git init
     ```
   - Клонировать существующий репозиторий:
     ```
     git clone <URL_репозитория>
     ```
     
## 3. Список основных команд

### 3.1. Основные команды

- Инициализация репозитория

  ```
  git init
  ```

  Создает новый локальный репозиторий Git в текущей директории.

- Клонирование репозитория

  ```
  git clone <url_репозитория>
  ```

  Создает копию существующего репозитория из удаленного источника.

- Просмотр статуса репозитория

  ```
  git status
  ```

  Показывает статус файлов в репозитории: изменения, готовые для коммита, неотслеживаемые файлы и т.д.

- Добавление изменений в индекс

  ```
  git add <файл>
  ```
  ```
  git add .
  ```

  Добавляет изменения файлов в индекс (staging area), подготавливая их для коммита.

- Создание коммита

  ```
  git commit -m "Описание изменений"
  ```

  Фиксирует добавленные изменения с сообщением, описывающим внесенные изменения.

- Просмотр истории коммитов

  ```
  git log
  ```

  Отображает список всех коммитов в текущей ветке.

- Создание новой ветки

  ```
  git branch <имя_ветки>
  ```

  Создает новую ветку без переключения на нее.

- Переключение на другую ветку

  ```
  git checkout <имя_ветки>
  ```

  Переключает текущую рабочую ветку на указанную.

  Либо комбинация создания и переключения:

  ```
  git checkout -b <имя_ветки>
  ```

- Слияние веток

  ```
  git merge <имя_ветки>
  ```

  Объединяет указанную ветку с текущей.

- Просмотр всех веток

  ```
  git branch
  ```

  Показывает список всех локальных веток.

- Отправка изменений в удаленный репозиторий

  ```
  git push origin <имя_ветки>
  ```

  Отправляет коммиты текущей ветки в удаленный репозиторий.

- Получение изменений из удаленного репозитория

  ```
  git pull
  ```

  Получает и автоматически сливает изменения из удаленного репозитория в текущую ветку.

- Просмотр различий между версиями

  ```
  git diff
  ```

  Показывает различия между рабочей директорией и индексом.

- Удаление ветки

  ```
  git branch -d <имя_ветки>
  ```

  Удаляет указанную ветку.

---

## 4. Сценарии использования

### 4.1. Создание новой ветки

Создание ветки позволяет работать над новой задачей или исправлением ошибки без влияния на основную версию документации.

#### Шаг 1: Создание новой ветки

1. Проверка актуальности главной ветки:
   - Перейдите в свою локальную копию репозитория.
   - Выполните команду ```git checkout main``` (или ```master```, в зависимости от структуры вашего репозитория).
   - Обновите ветку до последней версии с удаленного репозитория: ```git pull origin main```.

2. Создание новой ветки для работы над документацией:
   - Определите название для новой ветки. Например, ```update-docs```.
   - Создайте и переключитесь на новую ветку: ```git checkout -b update-docs```.

#### Шаг 2: Внесение изменений

3. Редактирование документации:
   - Откройте файлы документации в вашем текстовом редакторе или IDE.
   - Внесите необходимые изменения: добавьте новые разделы, обновите устаревшую информацию, исправьте ошибки и т.д.

4. Сохранение изменений:
   - После завершения редактирования сохраните все измененные файлы.

#### Шаг 3: Коммит изменений

5. Просмотр изменений:
   - Проверьте, какие файлы были изменены, с помощью команды ```git status```.

6. Добавление изменений в индекс:
   - Добавьте измененные файлы для коммита: ```git add .``` (добавит все изменения) или ```git add <имя_файла>``` для добавления конкретного файла.

7. Создание коммита:
   - Создайте коммит с описанием проделанной работы: ```git commit -m "Обновление документации: добавлены новые разделы и исправлены ошибки"```.

#### Шаг 4: Отправка на проверку

8. Отправка изменений на удаленный репозиторий:
   - Отправьте вашу ветку на удаленный репозиторий: ```git push origin update-docs```.

9. Создание Pull Request (PR):
   - Перейдите в интерфейс системы управления репозиторием (например, GitHub, GitLab или Bitbucket).
   - Создайте новый Pull Request из вашей ветки update-docs в основную ветку main.
   - В описании PR укажите детали внесенных изменений и при необходимости добавьте комментарии для ревьюеров.

10. Ожидание обратной связи:
    - Дождитесь проверки и одобрения вашего PR. При необходимости внесите правки по замечаниям.

11. Слияние ветки (после одобрения):
    - После одобрения изменений выполните слияние ветки в основную ветку через интерфейс системы управления репозиторием.

### 4.2. Обработка конфликтов при слиянии

Конфликты возникают, когда изменения в двух ветках противоречат друг другу.

**Шаги для разрешения конфликтов:**

1. **Попытка слияния:**

   ```bash
   git merge feature/some-feature
   ```

2. **Если возникают конфликты, Git уведомит вас о файлах с конфликтами.**

3. **Откройте конфликтующие файлы и исправьте конфликты вручную.** Конфликты обозначены специальными маркерами `<<<<<<<`, `=======`, `>>>>>>>`.

4. **После разрешения конфликтов добавьте файлы в индекс:**

   ```bash
   git add <файл>
   ```

5. **Завершите слияние коммитом:**

   ```bash
   git commit -m "Разрешены конфликты при слиянии feature/some-feature"
   ```

### 4.3. Совместная работа над проектом с применением системы контроля версий

Контекст:
Команда технических писателей работает над проектом, используя систему контроля версий (например, Git). Каждый участник отвечает за различные части документа, и периодически требуется сливать изменения в общую ветку (например, в ветку **main** или **develop**).

Участники:
1. Алексей - технический писатель, работающий над описанием функциональностью А.
2. Мария - технический писатель, работающий над описанием функциональностью Б.
3. Дмитрий - тимлид, ответственный за код-ревью и слияние изменений.

#### Шаги сценария:

1. Индивидуальная работа над задачами:
   - Алексей и Мария создают отдельные ветки (**feature/A** и **feature/B**) и реализуют свои задачи, регулярно коммитят изменения.

2. Подготовка к слиянию:
   - После завершения работы над задачами Алексей и Мария создают pull-реквесты (PR) для слияния своих веток с develop.

3. Код-ревью:
   - Дмитрий просматривает PR от Алексея и Марии, оставляет комментарии и предложения по улучшению кода.
   - Алексей и Мария вносят необходимые изменения и обновляют свои PR.

4. Проверка на конфликты:
   - Дмитрий локально сливает изменения из веток **feature/A** и **feature/B** с **develop**, чтобы убедиться в отсутствии конфликтов.
   - Обнаруживается конфликт в файле **example.md** из-за изменений, внесённых и Алексеем, и Марией.

5. Разрешение конфликтов:
   - Дмитрий идентифицирует конфликтующие участки кода (текста) и связывается с Алексеем и Марией для обсуждения.
   - Совместно они решают, какая логика должна быть сохранена, и вносят изменения в конфликтующий файл.
   - Дмитрий тестирует обновлённый файл, чтобы убедиться, что функциональность не нарушена.

6. Слияние изменений:
   - После успешного разрешения конфликтов и проверки Дмитрий обновляет ветку **develop** с учётом изменений из **feature/A** и **feature/B**.
   - Алексей и Мария удаляют свои временные ветки после успешного слияния.

7. Финальная проверка:
   - Команда проводит проверку, чтобы убедиться в корректной всей документации после слияния изменений.

8. Ретроспектива:
   - На следующей встрече команда обсуждает процесс слияния, выявляет возникшие проблемы и предлагает улучшения для будущих итераций.
  
### 4.4. Использование команд git merge и git rebase

**git merge** и **git rebase** — это два основных способа интеграции изменений из одной ветки в другую. Рассмотрим сценарии для каждого из них.

- **git merge** сохраняет историю всех веток, создавая коммит слияния. Это дает более полную картину того, как изменения были объединены, но может привести к более сложной истории коммитов.

- **git rebase** переписывает историю, что делает её более линейной и чистой. Однако следует быть осторожным при использовании rebase на общих ветках, так как это может привести к проблемам, если другие разработчики уже используют эту ветку.

Оба метода имеют свои преимущества и недостатки, и выбор между ними зависит от конкретного рабочего процесса и предпочтений команды.

#### 4.4.1. Сценарий использования git merge

1. Создание и переключение на новую ветку:
   
   ```bash
   git checkout -b feature-branch
   ```   
   Вы начинаете работу над новой функциональностью в отдельной ветке **feature-branch**.

2. Внесение изменений и коммит:
   
   ```bash
   # Внесите изменения в файлы
   git add .
   git commit -m "Add new feature"
   ```

4. Переключение на основную ветку:

   ```bash
   git checkout main
   ```

5. Интеграция изменений с помощью **merge**:

   ```bash
   git merge feature-branch
   ```
   
   Эта команда объединит изменения из **feature-branch** в **main**. Если есть конфликты, Git попросит вас их разрешить.

6. Удаление ветки (необязательно):

   ```bash
   git branch -d feature-branch
   ```
   
   После успешного мерджа можно удалить ветку, если она больше не нужна.


#### 4.4.2. Сценарий использования git rebase

1. Создание и переключение на новую ветку:

   ```bash
   git checkout -b feature-branch
   ```

1. Внесение изменений и коммит:

   ```bash
   # Внесите изменения в файлы
   git add .
   git commit -m "Add new feature"
    ```

2. Обновление основной ветки:

   ```bash
   git checkout main
   git pull origin main
   ```

3. Переключение обратно и выполнение **rebase**:
   
   ```bash
   git checkout feature-branch
   git rebase main
   ```
    
   Эта команда перепишет историю **feature-branch** так, как если бы она была создана на основе самого последнего состояния **main**.

5. Разрешение конфликтов (если есть):
   Если во время ребейза возникли конфликты, Git остановит процесс и предложит их разрешить. После разрешения конфликтов выполните:

   ```bash
   git add .
   git rebase --continue
   ```

6. Переключение на основную ветку и слияние:

   ```bash
   git checkout main
   git merge feature-branch
   ```
   
   После **rebase** слияние пройдет гладко, без дополнительных коммитов слияния.

7. Удаление ветки (необязательно):

   ```bash
   git branch -d feature-branch
   ```

---

## 4. Самые частые ошибки

### 4.1. Несохраненные изменения при переключении веток

**Ошибка:**

```bash
error: Your local changes to the following files would be overwritten by checkout:
```

**Решение:**

- **Сохраните изменения с помощью коммита:**

  ```bash
  git add .
  git commit -m "Сохранение изменений перед переключением ветки"
  ```

- **Или временно отложите изменения с помощью `stash`:**

  ```bash
  git stash
  git checkout <ветка>
  git stash pop
  ```

### 4.2. Отсутствие доступа к удаленному репозиторию

**Ошибка:**

```bash
fatal: Could not read from remote repository.
```

**Решение:**

- Убедитесь, что у вас есть правильные права доступа.
- Проверьте правильность URL удаленного репозитория.
- Проверьте настройки SSH или HTTPS (в зависимости от используемого протокола).

### 4.3. Неправильный коммит (коммит не содержит ожидаемых изменений)

**Возможные причины:**

- Файлы не были добавлены в индекс (`git add`).
- Вы добавили не те файлы.

**Решение:**

- Проверьте статус репозитория:

  ```bash
  git status
  ```

- Добавьте необходимые файлы:

  ```bash
  git add <файл>
  ```

- Создайте коммит снова:

  ```bash
  git commit -m "Корректные изменения"
  ```

### 4.4. Удаление нужных файлов

**Ошибка:**

Файлы были случайно удалены.

**Решение:**

- Проверьте, были ли изменения закоммичены:
  
  ```bash
  git log
  ```

- Восстановите файлы из последнего коммита:

  ```bash
  git checkout -- <файл>
  ```

---

## 5. Действия, которые могут что-то сломать необратимо

### 5.1. Использование `git push -f`

Команда `git push -f` (force push) перезаписывает историю ветки в удаленном репозитории, что может привести к потере работы других разработчиков.

**Когда следует использовать:**

- **Переписывание истории локальной ветки с уверенностью, что никто другой не работает с этой веткой.**

**Как избежать проблем:**

- **Используйте `--force-with-lease` вместо `--force`:**

  ```bash
  git push --force-with-lease
  ```

  Эта опция позволяет выполнить принудительную отправку только если удаленная ветка не была изменена другими пользователями.

- **Сообщайте команде** перед выполнением принудительной отправки, чтобы предотвратить конфликты.

### 5.2. Переписывание истории с помощью `git rebase` на публичных ветках

Использование `git rebase` для изменения истории коммитов публичных веток может вызвать проблемы для других разработчиков, работающих с этими ветками.

**Как избежать проблем:**

- **Используйте `git rebase` только для личных рабочих веток.**
- **Избегайте изменения общей истории, которая уже была отправлена в удаленный репозиторий.**

### 5.3. Удаление веток без проверки

Неосторожное удаление веток может привести к потере важных изменений.

**Команда для удаления ветки:**

```bash
git branch -d <имя_ветки>
```

Если ветка не была слита, используйте принудительное удаление:

```bash
git branch -D <имя_ветки>
```

**Как избежать проблем:**

- **Убедитесь, что ветка слита или изменения в ней больше не нужны.**
- **Сделайте резервную копию ветки перед удалением:**

  ```bash
  git branch backup/<имя_ветки>
  ```

### 5.4. Использование `git reset --hard`

Команда `git reset --hard` сбрасывает текущую ветку к указанному коммиту, удаляя все несохраненные изменения.

**Как избежать проблем:**

- **Избегайте использования `--hard`, если не уверены в последствиях.**
- **Используйте `git stash` для сохранения изменений перед сбросом:**

  ```bash
  git stash
  git reset --hard <коммит>
  git stash pop
  ```

- **Используйте `git reset` без `--hard`, чтобы сохранить изменения в рабочей директории.**

---

## 6. Рекомендации для дальнейшего обучения

- **Официальная документация Git**: [https://git-scm.com/doc](https://git-scm.com/doc)
- **Интерактивные курсы**:
  - [Try Git](https://try.github.io/)
  - [GitHub Learning Lab](https://lab.github.com/)
- **Книги**:
  - "Pro Git" Скотта Чакона и Бена Страуба (доступна бесплатно онлайн)

### 6.1. Полезные инструменты

- **Git GUI клиенты**:
  - [GitKraken](https://www.gitkraken.com/)
  - [Sourcetree](https://www.sourcetreeapp.com/)
  - [GitHub Desktop](https://desktop.github.com/)
- **Интеграция с IDE**:
  - Git поддерживается во многих IDE, таких как Visual Studio Code, IntelliJ IDEA, PyCharm и др.