GitLab и VS Code: от папки проекта до совместной работы

Часть 2 серии «AI-разработка в 1С». Предыдущая статья: Kilo Code с нуля.

Сначала организуем историю проекта и место для обмена изменениями. Затем научимся фиксировать работу, отделять эксперименты и проверять результат перед объединением. Все действия с Git выполняем кнопками штатного VS Code, без команд терминала.

Названия меню и снимки проверены в русскоязычном VS Code на рабочем компьютере 1 октября 2026 года. Для GitLab используем сервер организации git.imc-dmn.parus-s.ru. Его интерфейс зависит от установленной версии: английские названия действий GitLab приведены рядом с русским смыслом. Скриншоты ниже показывают VS Code; создание и проверка Merge Request описаны по документации GitLab.

1. Зачем нам нужен репозиторий

Проект — это не только работа с Заказчиком по Договору. В контексте VS Code проектом может быть любая папка с материалами, которые развиваются и которые нужно поддерживать согласованными.

Когда мы работаем только с папкой, легко получить инструкция_новая_финал_2.md и потерять понимание, какая версия актуальна. Репозиторий позволяет сохранять осмысленные этапы: «Добавить порядок согласования», «Исправить обработку пустого ответа», «Обновить схему отдела».

Это особенно полезно при работе с ИИ. Агент может изменить несколько файлов сразу. Git даёт возможность увидеть изменения строка за строкой, выбрать нужные и сохранить проверенный результат. Сам факт фиксации не означает, что результат агента корректен: проверка остаётся нашей задачей.

Git лучше всего показывает различия текстовых исходников: Markdown, BSL, XML, JSON, YAML. DOCX, PDF и изображения тоже можно хранить, но привычного сравнения строк и автоматического объединения для них обычно нет. Для 1С предпочтительны исходники в согласованном формате выгрузки; репозиторий не заменяет базу 1С и резервное копирование её данных.

Папка, Git и GitLab — три разных вещи

Сохранение файла, фиксация и отправка на сервер — отдельные действия. Пока мы только сохранили файл, он ещё не появился ни в истории Git, ни в GitLab. Локальная фиксация тоже ещё не отправлена коллегам.

2. Подготовка: создать проект в нашем GitLab

Шаг 1. Выбрать место и название

Войти в рабочий GitLab. Определить, где будет проект: в личном пространстве или группе команды. Для общих материалов заранее согласовать владельца и место хранения.

Название должно говорить о содержимом: imc-structure, ai-pilot, integration-oms. Адрес проекта включает пространство и короткое имя: например, /bazenkov/imc-structure.

Шаг 2. Создать пустой проект

Открыть New project / Новый проект → Create blank project / Создать пустой проект. Указать название, пространство, короткий адрес и описание. Для доступа только участникам выбрать Private, если правила команды не предусматривают другое.

Если файлы уже есть на компьютере и предстоит первая выгрузка, снять галочку Initialize repository with a README. Не создавать на сервере README, .gitignore или другие файлы до первой отправки. Они создадут отдельный серверный коммит.

Если же начинаем проект с GitLab, README можно создать: дальше нужно клонировать репозиторий и работать в его локальной копии. Это другой, столь же нормальный сценарий.

Поведение галочки README и создание проекта описаны в документации GitLab.

Шаг 3. Проверить права и скопировать адрес

Убедиться, что участники имеют нужный доступ. Отдельно проверить, разрешена ли отправка в main: право писать в проект не всегда означает право писать в защищённую ветку. Если main принимается только через Merge Request, первую загрузку организует ответственный или используется разрешённая ветка.

На странице проекта открыть Code / Clone и скопировать адрес репозитория. Выбрать уже настроенный в организации способ подключения. SSH требует ключа; HTTP/HTTPS — согласованного способа авторизации. Использовать адрес из GitLab, не составлять его по памяти.

В нашем примере адрес был:

http://git.imc-dmn.parus-s.ru/bazenkov/imc-structure.git/

3. Подключить папку к GitLab в VS Code

Выберите один из двух путей. Их различие — наличие истории на сервере и на компьютере. Git описывает эти два способа начала работы.

Вариант А. Файлы уже есть, серверный репозиторий пустой

1. Файл → Открыть папку… — открыть именно каталог проекта. Если репозиторий должен охватывать только его, не выбирать родительский каталог со всеми проектами. Если VS Code уже показывает Git-историю родительского репозитория, сначала определить границы репозитория: не создавать вложенный случайно.
2. Открыть слева «Система управления версиями». Нажать «Инициализировать репозиторий», если папка ещё не находится под Git. Если история уже есть, повторная инициализация не нужна. Для этих действий используется встроенный Git VS Code; GitLens устанавливать не требуется. Сам Git должен быть установлен на компьютере.
3. Подготовить .gitignore и проверить список файлов. Исключить временные файлы, локальные окружения и секреты. README и сам .gitignore включить в историю. Подробнее о правилах и пример файла — в разделе 5.
4. В разделе «Изменения» открыть файлы, проверить содержимое и нажать «+» / «Индексировать изменения» у тех файлов, которые должны попасть в первую фиксацию. Если проверен весь список, можно индексировать всё через плюс у заголовка раздела.
5. Ввести сообщение «Первоначальная загрузка проекта» и нажать «Фиксация». Если VS Code сообщает, что не задан автор Git, настроить рабочие имя и email по инструкции команды; вход в GitLab сам по себе не задаёт автора коммитов.
6. Проверить имя ветки. В этой статье используем main. Если первая ветка называется иначе, открыть ⋯ → Ветвь → Переименовать ветвь… и указать main, если это согласованная основная ветка проекта.
7. У строки репозитория открыть ⋯ → Удаленный → Добавить удаленный репозиторий…. Вставить адрес из GitLab и задать имя origin. Это имя подключения на компьютере, а не название проекта.
8. Нажать «Опубликовать Branch» / «Опубликовать ветвь» либо ⋯ → Ветвь → Опубликовать ветвь…. Если предлагается выбор подключения, выбрать origin. Здесь публикуется ветка в уже подключённый рабочий GitLab. Создавать новый проект на GitHub не требуется.
9. Открыть проект в GitLab: проверить файлы, ветку main и последнюю фиксацию. В VS Code вместо публикации появится синхронизация, а локальная и удалённая ветки будут связаны.

Меню открывается через ⋯ у строки репозитория. В нём находятся действия фиксации, получения, отправки и работы с ветками.

Путь подключения: «Удаленный → Добавить удаленный репозиторий…».

Для пустого сервера перед первой публикацией не нужны ни «Принесение», ни «Вытягивание». После подключения достаточно опубликовать локальную ветку. Настройка связи с удалённой веткой выполняется при успешной публикации.

Вариант Б. На сервере уже есть README, код или документы

1. Скопировать адрес проекта из GitLab.
2. В VS Code нажать F1 и выбрать «Git: Клонировать» или ⋯ → Клонировать.
3. Вставить адрес, выбрать родительскую папку для локальной копии и открыть полученный проект.
4. Если исходные материалы лежали в другой папке, перенести нужные файлы в клонированный проект, не перенося чужую служебную папку .git.
5. Проверить изменения и продолжить обычный цикл работы из следующего раздела.

Клонирование получает серверную историю и сразу настраивает подключение. Так мы избегаем отдельной начальной истории на каждой стороне. Если обе стороны уже имеют собственные коммиты, действуем по разделу 9, сохраняя обе истории.

Что означают origin, main и HEAD

origin — обычное имя удалённого подключения. Регистр и написание имеют значение: в одном нашем проекте имя было Origin, в текущем на снимках — otigin. Это локальные имена подключений; в новых проектах используем единое origin.

main — локальная основная ветка. origin/main — последнее известное локальному Git состояние серверной ветки. Обновить эти сведения можно через «Принесение».

origin/HEAD — указатель на основную ветку сервера, часто на origin/main. При выборе ветки для работы выбирайте явно origin/main. Просто HEAD обозначает текущую позицию в вашей локальной истории.

4. Как работать каждый день: изменили → проверили → зафиксировали → отправили

Перед началом работы

Проверить название проекта и активную ветку внизу окна. При чистом рабочем состоянии получить новые изменения через ⋯ → Вытягивание. Если в папке есть незавершённые правки, сначала разобраться с ними: закончить и зафиксировать либо осознанно отложить. Не начинать переключение веток наугад.

Шаг 1. Изменить и сохранить файлы

Выполнить одну понятную задачу. Например, добавить инструкцию или исправить обработку ответа сервиса. Сохранить изменённые файлы. Они появятся в «Изменениях»: M — изменён, U — новый неотслеживаемый файл, D — удалён.

Шаг 2. Проверить и добавить в список фиксации

Нажать на файл в «Изменениях»: откроется сравнение прежнего и нового содержимого. Проверить, что нет случайных удалений, посторонних правок и файлов, которые не должны отправляться.

Затем нажать «+» — «Индексировать изменения». Это подготовка выбранного содержимого к коммиту. Если после индексирования файл снова редактировался, новые правки нужно проверить и индексировать повторно. Через минус можно снять подготовку, сохранив правки в файле.

Не обязательно вести отдельный документ со списком всех изменений: список файлов и сравнение уже доступны в Git. Для содержательной задачи полезно дополнительно описать, что поменялось и почему, в сообщении фиксации или Merge Request.

Слева — файлы для проверки и поле сообщения; справа — сравнение версий. На снимке — обновление README с добавлением второй статьи.

Шаг 3. Дать фиксации понятное имя

Ввести сообщение в поле «Сообщение». Оно описывает общий смысл выбранного набора изменений:

• «Добавить порядок согласования архитектурных решений»;
• «Исправить загрузку пустого ответа сервиса»;
• «Обновить инструкцию подключения к GitLab».

Кнопки «Сгенерировать сообщение о фиксации», «Сгенерировать сообщение коммита» или Generate Commit Message могут предложить текст с помощью установленного AI-инструмента. Доступность генерации зависит от расширения и подключения. Проверить предложение и исправить его перед фиксацией: ИИ может неверно описать назначение изменений.

Шаг 4. Зафиксировать

Нажать «Фиксация». Подготовленное содержимое попадёт в локальную историю. Одна фиксация должна иметь объяснимый смысл: исправление ошибки и большая переработка регламента обычно заслуживают разных коммитов.

Шаг 5. Отправить

Для новой ветки — «Опубликовать ветвь». Для уже связанной — ⋯ → Отправка или стрелка вверх в «Графе». Проверить результат в GitLab. Если отправка отклонена, открыть журнал, выяснить причину и только затем повторять.

Последовательность сохранения, подготовки, коммита и отправки описана в руководстве VS Code.

Получение и отправка: русские названия кнопок

«Принесение» и «Отправка» направлены в разные стороны. «Синхронизация» объединяет несколько действий.

5. .gitignore: что включать в историю

.gitignore задаёт правила исключения неотслеживаемых файлов. Сам файл .gitignore включаем в репозиторий: команда должна видеть общие правила.

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

Как создать файл и что в него написать

В «Проводнике» VS Code нажать правой кнопкой на папку проекта → «Новый файл…» и задать имя .gitignore, без расширения .txt. Создать его в корне проекта, рядом с README. Если файл уже есть, дополнить существующие правила.

Например, для каталога статей со сборкой сайта файл может выглядеть так:

# Служебные файлы macOS
.DS_Store

# Локальное окружение и промежуточные файлы сборки
/work/.venv/
/work/mkdocs-docs/

# Готовые экспорты, которые можно собрать заново
/exports/

# Кэш Python
__pycache__/
*.pyc

# Локальные параметры и секреты, если они хранятся в таких файлах
.env
.env.*
!.env.example

Строки с # — комментарии. Завершающий / обозначает каталог; начальный / привязывает правило к корню, если .gitignore находится в корне проекта. *.pyc исключает файлы с таким расширением, а ! отменяет исключение: безопасный шаблон .env.example можно хранить в истории. В нём должны быть только примеры параметров, без настоящих паролей и токенов.

Это пример для нашего типа проекта: первые правила соответствуют текущему .gitignore каталога статей, правила .env показаны как возможное дополнение. Их нужно адаптировать к фактическим файлам проекта. Исходники .md, изображения в assets/, настройки сборки, README и сам .gitignore остаются в репозитории.

Сохранить файл и вернуться в «Систему управления версиями». Проверить, что исключённые неотслеживаемые файлы исчезли из списка, а .gitignore остался доступен для индексирования и фиксации.

Для конфигурации 1С правила зависят от формата исходников и инструментов команды. Нельзя исключать весь XML или BSL только потому, что это большие каталоги: там могут находиться исходники.

Важная граница: добавление имени уже отслеживаемого файла в .gitignore не удаляет его из истории и не прекращает автоматически отслеживание. Поэтому состав первой загрузки проверяем до фиксации. Секрет, попавший в коммит, нельзя считать устранённым только после добавления правила исключения.

6. Когда нужна новая ветка

Если работаем один

Для небольших завершённых правок в личном проекте можно работать в main, если правила проекта это разрешают. Ветка полезна, когда результат ещё экспериментальный, задача займёт несколько этапов или нужно сохранить готовую версию для текущего использования.

Например, исправить опечатку можно в main. Переработать весь регламент, изменить структуру документации или поручить ИИ реорганизацию модулей удобнее в отдельной ветке: docs/new-regulation, feature/import-checks, experiment/new-layout.

Ветка не создаёт отдельную резервную копию папки. При переключении VS Code показывает файлы выбранной линии истории. Чтобы сохранить незавершённую работу на сервере, нужно фиксировать и отправлять её в свою ветку.

Если работает команда

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

На одну логическую задачу создаём одну ветку. Затем публикуем её и открываем Merge Request. В GitLab это называется Merge Request, хотя в разговоре часто говорят «пулл-реквест». Ответственный проверяет изменения и принимает решение о слиянии. Для защищённой main это также может быть обязательным правилом сервера.

Какие кнопки нажимать и в каком порядке: создание и публикация ветки — в разделе 7, создание Merge Request и проверка результата — в разделе 8.

7. Создать ветку и объединить её через VS Code

Начать задачу в ветке

1. Закончить предыдущую задачу; проверить, что нет неучтённых изменений.
2. Нажать на имя ветки внизу окна, выбрать main и выполнить Вытягивание, если main связана с сервером.
3. Открыть ⋯ → Ветвь → Создать ветвь….
4. Ввести имя, например docs/gitlab-guide. Ветка создаётся от текущего состояния. Для выбора другой исходной точки есть «Создать ветвь из…».
5. Убедиться, что внизу окна показано новое имя. Выполнить задачу, проверить и зафиксировать изменения.
6. Нажать «Опубликовать ветвь». Последующие коммиты отправлять через «Отправка».

Все основные действия доступны в штатном меню «Ветвь».

Объединить самостоятельно, если проверяющий не требуется

1. Проверить результат в рабочей ветке и зафиксировать его.
2. Переключиться на main через имя ветки внизу окна.
3. Получить актуальное состояние main через Вытягивание.
4. Выбрать ⋯ → Ветвь → Объединить… и указать ветку задачи, например docs/gitlab-guide.
5. Разрешить конфликты, если они возникли. Проверить итоговый проект. Если Git ожидает фиксацию результата слияния, завершить её.
6. Выполнить Отправку и проверить GitLab.
7. После успешного объединения и проверки можно удалить завершённую локальную ветку через Ветвь → Удалить ветвь…, находясь в main.

Объединение идёт в текущую ветку. Если нужно добавить задачу в main, сначала переключаемся в main, затем выбираем ветку задачи для объединения. Если же обновляем ветку задачи из основной, остаёмся в ветке задачи и выбираем main.

Механика слияния описана в книге Git. Удалять ветку до проверки принятого результата не нужно.

8. Командная работа: ветка → Merge Request → проверка → слияние

Автор изменений

После публикации своей ветки открыть проект в GitLab:

1. Merge requests → New merge request.
2. Указать Source branch — ветку задачи; Target branch — main или другую согласованную ветку.
3. Нажать Compare branches and continue.
4. Добавить название, описание проблемы, выполненных изменений и проверки. Назначить ответственного за рассмотрение в поле Reviewer, если оно доступно.
5. Нажать Create merge request. Для незавершённой работы использовать Draft.

В описании полезно указать три вещи: что изменилось, зачем и как проверено. Для документа — какое правило изменено и с какими связанными материалами сверено; для кода — проверяемый сценарий и результат проверки.

Автор продолжает исправления в той же ветке: редактирует, фиксирует и отправляет. Merge Request получает новые коммиты. Новый запрос на каждое замечание не нужен.

Ответственный за проверку

В Merge Request открыть Changes и посмотреть различия, затем историю Commits и обсуждения. Проверить соответствие задаче, полноту результата, отсутствие случайных файлов и согласованность со смежными изменениями.

Замечания оставлять возле конкретных строк или в общем обсуждении. Запрашивать исправления, если необходимо. Автоматические проверки, если они настроены, должны завершиться успешно. Одобрение Approve доступно в зависимости от версии, лицензии и правил проекта; назначение Reviewer само по себе не гарантирует обязательного блокирующего одобрения.

После проверки ответственный нажимает Merge согласно правилам проекта. Если основная ветка защищена, разрешения на слияние настраивает владелец проекта. Локальное объединение автором не заменяет предусмотренную проверку.

После слияния автор переключается в VS Code на main, выполняет Вытягивание и убеждается, что принятые изменения доступны локально.

Возможности обсуждения, проверки и объединения описаны в документации Merge Request GitLab.

Как выявлять противоречия и расхождения

Есть два разных вида проблем:

Пример текстового конфликта: два автора по-разному переписали один пункт регламента. Пример смыслового: один изменил срок согласования в инструкции на два дня, другой оставил пять дней в схеме процесса. Git может объединить разные файлы без предупреждения, но правила будут противоречить друг другу.

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

До слияния сравнить ветку задачи с актуальной целевой веткой, просмотреть все изменённые файлы и проверить связанный сценарий. При необходимости обновить ветку задачи: получить актуальную main, вернуться в ветку задачи и через Ветвь → Объединить… добавить main. Решить конфликты, проверить результат, зафиксировать при необходимости и отправить ветку. Для общей ветки задачи такой merge сохраняет опубликованную историю; rebase уже опубликованных коммитов требует согласования.

Разрешить конфликт в VS Code

Открыть конфликтующий файл из раздела слияния в «Системе управления версиями». VS Code показывает текущую и входящую версии; можно использовать редактор слияния с отдельным результатом или предложения принятия изменений возле конфликтных блоков. Надписи этих кнопок зависят от режима и версии; в этой статье не приводится постановочный снимок конфликта.

Не выбирать «принять всё» по привычке. «Текущее» и «входящее» зависят от выполняемой операции, особенно при rebase. Прочитать обе версии и сформировать нужный результат: иногда нужен один вариант, иногда сочетание, иногда новый текст.

Сохранить файл, убедиться, что не остались маркеры конфликта, проверить результат и индексировать разрешённые файлы. При обычном merge завершить Фиксацию; при rebase продолжить именно начатое перемещение через предложенное VS Code действие. Пока операция не завершена, не начинать новую публикацию.

Инструменты разрешения конфликтов описаны в руководстве VS Code.

9. Если первая отправка не прошла: ошибки из нашего подключения

Этот раздел нужен для существующей проблемы, а не как обязательные этапы подключения.

«Сначала выберите “Извлечь”, чтобы интегрировать изменения»

Сервер отклонил отправку, потому что локальная история не содержит нужных серверных коммитов. Нажать «Показать выходные данные команды» или открыть ⋯ → Показать выходные данные GIT. Прочитать конкретную причину. Надпись в диалоге может говорить «Извлечь», хотя в меню действие называется «Вытягивание».

«There is no tracking information for the current branch»

Локальная ветка не связана с серверной. Обычное Вытягивание и Получить (переместить изменения из одной ветви в другую) не знают источник. Через ⋯ → Вытягивание, отправка → Получить из… можно явно выбрать подключение и main. Это выбор для получения, а не гарантия постоянной настройки связи.

Если сервер пустой, решением обычно является первая успешная публикация ветки. Если на сервере уже есть коммиты, сначала нужно объединить истории. Не повторять публикацию, не разобрав расхождение.

«You have divergent branches» / «Need to specify how to reconcile»

Коммиты есть с обеих сторон; обычное вытягивание требует выбрать способ интеграции. В нашем случае локальные коммиты ещё не были опубликованы, и мы выполнили перенос поверх серверной main:

1. Убедились, что рабочие изменения зафиксированы и состояние чистое.
2. Через F1 → Git: Принесение получили сведения о серверной ветке.
3. Через F1 → Git: Перемещение изменений из одной ветви в другую… выбрали именно Origin/main — фактическое имя подключения в том проекте. Это действие над веткой, а не обычный Pull с rebase, которому нужна настроенная связь.
4. После успешного переноса нажали «Опубликовать Branch».
5. Проверили, что main и Origin/main показывают один коммит и вместо публикации появилась синхронизация.

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

«warning: redirecting to…»

В нашем журнале сервер перенаправлял запрос на адрес репозитория с завершающим /. Само предупреждение не объясняло сбой: причина находилась ниже. Использовать адрес из GitLab и читать журнал целиком, а не исправлять историю из-за строки предупреждения.

10. Короткий рабочий чек-лист

Первое подключение существующей папки: пустой проект GitLab → открыть папку → инициализировать Git при необходимости → .gitignore → проверить и индексировать файлы → первая фиксация → имя main → добавить origin → опубликовать ветку → проверить GitLab.

Обычная задача: выбрать нужную ветку → получить актуальные изменения → изменить и сохранить → проверить сравнение → индексировать → дать понятное сообщение → зафиксировать → отправить.

Командная задача: актуальная main → новая ветка → работа и проверки → публикация → Merge Request → замечания и исправления → проверка ответственным → слияние → вытягивание обновлённой main.

Перед фиксацией задать себе три вопроса: в той ли я ветке, все ли изменения относятся к задаче и проверил ли я результат? Перед слиянием добавить четвёртый: согласован ли результат с актуальной основной версией?