Setting up a Git repository for a 1C-Bitrix project

Git Repository Setup for a 1C-Bitrix Project

Adding a Bitrix project to git is a non-trivial task. The platform core weighs half a gigabyte, contains binary files, and is updated through its own updater rather than via code review. Adding /bitrix/ to the repository means the very first git push uploads hundreds of megabytes, and the commit history turns into a dump of core changes. Proper repository setup starts with a clear answer to the question: what should actually live in git.

What to Store in Git and What Not To

Only what the team develops goes into the repository:

local/                  ✅ — all custom components, modules, templates
.env.example            ✅ — configuration example without secrets
deploy/                 ✅ — deploy scripts, docker-compose
nginx.conf.example      ✅ — web server config template

Outside the repository:

bitrix/                 ❌ — platform core
upload/                 ❌ — user-generated content
.env                    ❌ — secrets
bitrix/php_interface/dbconn.php  ❌ — database credentials

Basic .gitignore

# Bitrix core
/bitrix/

# User-generated content
/upload/

# Configuration with secrets
/.env
/bitrix/php_interface/dbconn.php

# Cache
/bitrix/cache/
/bitrix/managed_cache/
/bitrix/stack_cache/

# IDE
/.idea/
/.vscode/
*.swp

# Node.js (if used in local/)
/local/node_modules/
/local/.npm/

# OS
.DS_Store
Thumbs.db

Initializing an Existing Project

If the project already exists on the server and git was not set up from the beginning:

cd /var/www/myshop

# Initialize the repository
git init
git remote add origin [email protected]:projects/myshop.git

# Create .gitignore BEFORE the first add
# (add the content from the example above)
nano .gitignore

# Add only /local/ and config files
git add local/
git add .gitignore
git add deploy/
git add nginx.conf.example
git add .env.example

git commit -m "Initial commit: local customizations"
git push -u origin main

If /bitrix/ was accidentally added to the index before creating .gitignore:

git rm -r --cached bitrix/
git rm -r --cached upload/
git commit -m "Remove bitrix/ and upload/ from tracking"

Branches and Workflow

A simplified GitFlow works well for Bitrix projects:

main         — production code, deployed only through CI
develop      — main development branch, deployed to staging automatically
feature/*    — tasks (feature/JIRA-123-new-filter)
hotfix/*     — urgent production fixes

Commit convention — Conventional Commits:

feat(catalog): add ajax filter component
fix(checkout): fix payment handler null reference
refactor(local): move common functions to helpers

Working with Configuration Files

Database connection parameters and other secrets go in .env, which is not committed. In bitrix/php_interface/dbconn.php they are pulled in via $_ENV or getenv():

// dbconn.php — NOT in git, created on the server manually or via deploy script
$DBHost = getenv('DB_HOST') ?: 'localhost';
$DBLogin = getenv('DB_USER') ?: 'bitrix';
$DBPassword = getenv('DB_PASSWORD') ?: '';
$DBName = getenv('DB_NAME') ?: 'bitrix_db';

.env.example is committed and contains keys without values:

DB_HOST=
DB_USER=
DB_PASSWORD=
DB_NAME=
SMTP_HOST=

Timeline