How to Use Version Control (Git) with WordPress

“Good software, like wine, gets better with time… but only if you can track the bottle.”

Whether you’re a solo WordPress developer, a freelancer juggling client work, or part of a larger development team, you’ve likely run into a few of these frustrating situations:

You made changes to your theme and now something’s broken — but you’re not sure what changed.
Your client wants to “revert to what we had last week”… and you didn’t keep a copy.
You’re collaborating on a project and accidentally overwrote your teammate’s code.

Sound familiar? That’s where version control — and Git in particular — becomes a game-changer.

🚀 What This Guide Is About

This is your complete, beginner-friendly yet deep-dive guide on how to use Git effectively within the WordPress ecosystem.

We’ll explore everything from:

Setting up Git with WordPress the right way
Structuring your repositories
Smart workflows for solo devs and teams
Deployment strategies (manual, Git-based, CI/CD)
Real-world tips, common pitfalls, and best practices

All wrapped in a clear, visual, and hands-on learning experience.

🧑‍💻 Who This Guide Is For

Beginner developers who want to stop manually zipping WordPress folders
Freelancers looking for better project control and backup
Agencies who need structured collaboration tools
Any WordPress professional ready to level up their development game

🧠 Tip: If you know what FTP is but haven’t used git commit before — this guide is perfect for you.

🧱 Why Git + WordPress Makes Sense

Here’s what Git brings to your WordPress workflow:

🌟 Benefit	💬 What It Means
Track Every Change	Know exactly what was changed, when, and by whom
Safe Experimentation	Try new things in branches without breaking the site
Instant Rollbacks	Revert to a previous version with a single command
Team Collaboration	Multiple devs can work on the same project without overwriting each other
Cleaner Deployments	Deploy only the files you need, when you want

✅ Pro Tip: You don’t need to put your entire WordPress site in Git — and you shouldn’t. We’ll show you exactly what to track (and what to ignore).

📌 What You’ll Need

This guide assumes you have:

A basic working knowledge of WordPress
Access to a WordPress site (locally or hosted)
Git installed on your machine (don’t worry, we’ll walk through that too)
Optional: GitHub, GitLab, or Bitbucket account for remote backups and collaboration

🎯 Final Thought Before We Begin…

If you’ve ever manually copied a WordPress site by dragging folders or sending ZIP files to clients… it’s time to evolve.

Git isn’t just for hardcore developers. Once you see what it can do for your WordPress projects, you’ll never go back.

Let’s dive in. 🧑‍💻👇

🔍 Understanding Version Control & Git

Before we dive into setting up Git with WordPress, it’s essential to understand what version control is, and why Git is the go-to tool for modern development workflows — including WordPress.

📦 What Is Version Control?

Version control is a system that helps you track changes to files over time. It lets you:

Go back to any previous version of your work
Experiment without fear of losing progress
Collaborate with others more effectively

Think of it like an “infinite undo” button — but much smarter.

🧠 Tip: Version control isn’t just for code — it can manage configuration files, assets, or even documentation.

🐙 What Is Git?

Git is the most widely used version control system in the world. It’s free, open-source, lightning-fast, and works both offline and online.

Originally created by Linus Torvalds (yes, the creator of Linux), Git has become the backbone of modern software development — including the platforms that power WordPress plugins, themes, and core contributions.

Why Git Stands Out:

It tracks changes locally (on your machine)
You can branch and merge with ease
It integrates beautifully with services like GitHub, GitLab, and Bitbucket
It works offline — you don’t need internet to use Git

💡 Git vs. No Git: A Workflow Comparison

Without Git	With Git
Manual backups (zip files)	Automated history of every change
No clear record of what changed or when	Each change is recorded and reversible
Risk of overwriting others’ work	Safe branching for parallel development
Deployments are messy and manual	Deploy only tracked, tested code

✅ Pro Tip: You can even use Git to track database scripts, changelogs, and update notes — just be cautious about sensitive data.

🧰 Key Git Concepts to Know

Here are a few essential Git terms you’ll see often:

Repository (Repo): A folder tracked by Git. Think of it as your project’s version-controlled home.
Commit: A snapshot of changes. Each commit is like a checkpoint in your project history.
Branch: A parallel version of your code. Useful for working on new features without touching the main code.
Merge: Combining changes from one branch into another (e.g., feature → main).
Remote: A version of your Git repository hosted on a server (like GitHub or GitLab).
Push/Pull: Sending changes to a remote repo (push) or fetching updates from it (pull).

🌍 Why WordPress Developers Should Care

WordPress may have humble roots as a blogging platform, but it’s now a full-fledged CMS powering over 40% of the web. And as your projects grow in complexity, so does the risk of breaking something without knowing how to undo it.

That’s why Git is essential — even for WordPress sites.

Using Git doesn’t make you a “developer” — it makes you a responsible WordPress builder.

Now that you have the context, let’s roll up our sleeves and look at how WordPress is structured — so we can start applying Git effectively.

🧱 Understanding the WordPress File Structure

To use Git effectively with WordPress, it’s important to understand how WordPress is structured. This will help you decide which parts of your site to track with Git — and which to leave out.

🗂️ What’s Inside a Typical WordPress Directory

When you unzip or install WordPress, your site directory usually contains these main components:

wp-admin/ – The WordPress dashboard and admin UI files
wp-includes/ – Core WordPress functionality (libraries, classes, APIs)
wp-content/ – Your themes, plugins, and uploads — this is where your custom work lives
index.php, wp-config.php, etc. – Core bootstrap and configuration files

🧠 Tip: The only folder you should typically version control is wp-content. The rest can be restored by reinstalling WordPress core.

✅ What You Should Track with Git

Here’s what you’ll usually want to include in your Git repository:

Custom themes – e.g., wp-content/themes/my-theme
Custom plugins – e.g., wp-content/plugins/my-plugin
Must-use plugins (if any) – e.g., wp-content/mu-plugins/
Optional: wp-config.php, if you customize it (excluding credentials)

🚫 What You Should Ignore in Git

There are parts of WordPress you usually don’t want to track in Git:

Core files – WordPress updates regularly; you don’t want to manage core code
Uploads folder – wp-content/uploads contains user content and media, not code
Database – WordPress stores site content and settings in the database, not in files
Auto-generated or cache files

To ignore these safely, you’ll use a .gitignore file — which we’ll cover in the setup section next.

🧭 Common Folder Overview

Here’s a brief look at what stays in Git and what doesn’t:

Tracked: wp-content/themes/, wp-content/plugins/, wp-config.php (optional)
Ignored: wp-admin/, wp-includes/, wp-content/uploads/, *.log, node_modules/ (if present)

✅ Pro Tip: When working in teams, always share a consistent .gitignore to avoid accidentally committing large or sensitive files.

🔒 A Word on wp-config.php

wp-config.php contains your database credentials and sensitive keys. If you track it in Git, be sure to:

Use wp-config-sample.php for sharing safe defaults
Exclude any environment-specific secrets or move them to an ignored .env file

🧠 Security Tip: Never commit database passwords or secret keys to a public Git repository.

🎯 Summary

Track your wp-content folder — themes and plugins only
Ignore uploads, WordPress core, and temporary files
Use a .gitignore to keep your repo clean
Handle sensitive data with care — don’t commit secrets

With this understanding, you’re ready to actually start using Git with your WordPress project. Next, we’ll walk through setting up your first Git repository, step by step.

🚀 Setting Up Git for WordPress

Now that you understand the WordPress file structure and what to track, it’s time to get hands-on. Let’s set up Git in your local WordPress project so you can start version-controlling your code like a pro.

🛠️ Prerequisites

Before we begin, make sure you have the following ready:

Git installed on your system (git --version to check)
A local WordPress site (e.g., using Local by Flywheel, XAMPP, MAMP, DevKinsta, or similar)
Command line/terminal access

💡 Need Git? Download it here for Windows, macOS, or Linux.

📁 Step 1: Navigate to Your Project Folder

Open your terminal and navigate to your WordPress root directory (where wp-content lives):

cd path/to/your-wordpress-site

Alternatively, if you only want to track a custom theme or plugin, navigate directly into that folder:

cd wp-content/themes/your-theme

🧱 Step 2: Initialize Git

Initialize a new Git repository with this command:

git init

This creates a hidden .git folder that tracks changes to your files.

📦 Tip: Run ls -a to see hidden files like .git.

🚫 Step 3: Create a .gitignore File

Now tell Git which files and folders to ignore. In your project root, create a file named .gitignore with the following example contents:

# Ignore WordPress core files
wp-admin/
wp-includes/

# Ignore uploads and personal media
wp-content/uploads/

# Ignore OS and editor files
.DS_Store
Thumbs.db

# Ignore log files and cache
*.log
cache/
tmp/

# Ignore dependency folders
node_modules/
vendor/

# Optional: ignore sensitive config
wp-config.php
.env

Customize this list based on your setup — the key is to track only code you control.

📸 Step 4: Stage and Commit Your Code

Stage all the files you want to track:

git add .

Then create your first commit:

git commit -m "Initial commit – added custom theme and plugin files"

Now Git has a snapshot of your code’s current state.

🌐 Step 5: Connect to a Remote Repository (Optional)

If you want to store your code on a platform like GitHub, GitLab, or Bitbucket:

Create a new empty repository on your chosen platform
Copy the remote URL (usually ends in .git)
Connect it to your local repo:

git remote add origin https://github.com/your-username/your-repo.git

Then push your code:

git push -u origin main

📘 Note: If your default branch is called master instead of main, update the command accordingly.

🔁 Bonus: Clone a WordPress Git Repo

If you’re working on a project someone else started, you can clone it like this:

git clone https://github.com/example/wordpress-site.git

This will download the repo into a folder with its Git history intact. You’ll need to install WordPress separately or pull in the missing parts (like uploads or database).

🔄 Git Workflow for WordPress Projects

Now that your WordPress project is version-controlled with Git, it’s time to learn how to actually use Git day-to-day. A good workflow helps you stay organized, collaborate smoothly, and ship changes safely.

Here’s how you can structure your Git workflow to work naturally with WordPress development — whether you’re solo or part of a team.

🌳 Step 1: Use Branches for Features and Fixes

A Git branch lets you safely work on changes without touching your main code. Create a new branch for each feature, bugfix, or experiment:

git checkout -b feature/custom-login-page

Make your changes, test them, and then merge them back into the main branch:

git checkout main
git merge feature/custom-login-page

🌱 Tip: Use short, descriptive branch names like fix/footer-layout or feature/add-slider.

💾 Step 2: Make Frequent, Clear Commits

Instead of committing one giant change, make small, focused commits that describe what was changed and why:

git add .
git commit -m "Fix: Adjust footer alignment on mobile"

This makes it easier to roll back or understand the project history later.

📥 Step 3: Pull Often When Working with Others

If you’re working with collaborators, always pull the latest changes before pushing yours:

git pull origin main

This ensures your work is built on the most recent version and helps avoid conflicts.

📤 Step 4: Push Your Work Regularly

Don’t keep your work only on your machine. Push changes to the remote repo to keep your code backed up and visible:

git push origin feature/custom-login-page

Once merged, you can delete the branch locally and remotely (optional but clean):

git branch -d feature/custom-login-page
git push origin --delete feature/custom-login-page

🛠️ Optional: Use Pull Requests (or Merge Requests)

If you’re using GitHub, GitLab, or Bitbucket, open a pull request (PR) to review and discuss changes before merging.

This is especially useful for team environments, and even solo developers benefit from code review checkpoints.

🧠 Best Practice: Use pull requests to keep your main branch stable and deployable at all times.

♻️ Step 5: Rolling Back Mistakes

Git makes it easy to undo mistakes without panic. Here are a few handy commands:

Undo the last commit (but keep changes): git reset --soft HEAD~1
Discard local changes in a file: git checkout -- filename.php
View history: git log --oneline

Once you’re confident with these, your development workflow becomes far more flexible.

🚦 Example Workflow Summary

Pull latest changes: git pull origin main
Create a branch: git checkout -b feature/some-task
Make changes, test locally
Commit changes: git commit -m "Add: something useful"
Push your branch: git push origin feature/some-task
Open a pull request and merge
Clean up: git branch -d and delete remote branch if needed

✅ Tip: Commit often, merge cautiously, and always test before pushing.

🧪 Git in Local WordPress Development

Most WordPress developers work locally — building, testing, and experimenting on their own machine before going live. Using Git locally gives you version history, a safety net for mistakes, and a powerful workflow to keep your codebase clean and traceable.

🖥️ Common Local Development Tools

Before we dive into Git-specific advice, here are a few popular tools developers use to run WordPress locally:

Local by Flywheel / WP Engine – User-friendly with GUI interface and WordPress-specific tooling
XAMPP / MAMP / WAMP – Classic local stacks for PHP, MySQL, Apache/Nginx
DevKinsta – Designed for Kinsta users, but usable by all
Laravel Valet – For Mac users who prefer lightweight setups
Docker – Flexible, modern approach using containers

💡 Tip: Use a local tool that supports quick site creation and makes your life easier. All of them work with Git!

📁 Recommended Local Git Project Structure

When working locally with Git and WordPress, you have two main options:

Option 1: Track the Entire WordPress Project

Track everything except uploads, core, and config files:

your-wordpress-site/
├── wp-content/
│   ├── themes/
│   └── plugins/
├── .gitignore
├── .git/
└── README.md

Pros:

Full visibility into your development site
Simple to manage in solo projects

Cons:

Can get messy if you commit core files or uploads accidentally
Not ideal for teamwork unless tightly controlled

Option 2: Track Only Your Theme or Plugin

Navigate into your theme/plugin folder and initialize Git there:

cd wp-content/themes/my-theme
git init

Pros:

Focused, lightweight repositories
Perfect for custom themes or plugins distributed independently

Cons:

Requires manual installation into WordPress (or symbolic linking)
May not capture broader site-level changes

🧪 Working Locally with Git: Daily Tasks

Here’s what a typical day in Git-based WordPress development might look like:

Start work: Pull the latest changes, create a feature branch
Make updates: Code in your theme/plugin, test in the browser
Commit frequently: Save your progress in small commits
View history: Use git log to see your progress
Finish feature: Merge the branch into main and push

🔗 Bonus: Link Git Repo to Deployment Tools

Many tools let you deploy your Git-tracked files directly to staging or production:

GitHub Actions / Bitbucket Pipelines: Automate deployments on push
DeployBot / Buddy / Beanstalk: Visual deploy workflows
WP Engine, Kinsta, Pantheon: Git-friendly hosting environments

⚡ Pro Tip: You can configure Git to auto-deploy theme changes to your staging site every time you push to a specific branch like staging.

📁 Example: Using Git with Local by Flywheel

Let’s walk through a quick real-world scenario using Local by Flywheel:

Create a new WordPress site in Local
Navigate to the theme folder:cd ~/Local Sites/my-site/app/public/wp-content/themes/my-theme
Run:git initgit add .git commit -m "Initial commit – custom theme structure"
Connect a remote repo if needed:git remote add origin https://github.com/user/my-theme.gitgit push -u origin main

🚀 Git and Deployment Strategies

Version control is amazing on its own — but when you combine Git with smart deployment strategies, it unlocks a new level of power. Whether you’re a solo dev or part of a team, deploying with Git makes updates faster, safer, and more traceable.

Let’s explore the best ways to deploy WordPress projects using Git and what tools can help automate the process.

📦 What Should You Deploy?

Before we look at methods, it’s worth asking: what parts of your WordPress site should be deployed via Git?

Yes: Custom themes, plugins, MU-plugins, and other code
Maybe: Configuration files (e.g., wp-config.php), depending on environment
No: Media uploads, the wp-content/uploads folder, user-generated content, or the database

⚠️ Important: Git is for code, not content. Keep that separation clean to avoid overwriting live data.

📤 Strategy 1: Manual FTP/SFTP Deployment (Baseline)

This method uses Git locally, then uploads files manually to your server:

Commit your changes locally
Export a ZIP of the theme/plugin folder
Upload via FTP/SFTP using FileZilla or similar

✅ Simple, works anywhere — but ⚠️ prone to human error and not scalable.

⚙️ Strategy 2: Git-Based Deployment via Host Integration

Some managed WordPress hosts support Git integration directly:

WP Engine – Push code to a Git endpoint, which deploys it automatically
Kinsta – Use Git to track changes, then deploy with tools like DevKinsta or SSH
Pantheon – Git-powered workflow with development/staging/live environments

git remote add production git@git.wpengine.com:environment.git
git push production main

✅ Great for teams, repeatable and safe — but requires compatible hosting.

🤖 Strategy 3: Automated Deployment Tools

These tools connect your Git repo to a live server and automate deployments on push:

DeployBot – Easy setup, deploy on push, integrates with GitHub/GitLab
Buddy – Visual automation pipelines for building and deploying
GitHub Actions – Configure CI/CD workflows with YAML files
Bitbucket Pipelines – Similar CI/CD for Bitbucket users

Sample GitHub Action (deploys a theme via SFTP):

name: Deploy Theme via SFTP

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repo
        uses: actions/checkout@v2

      - name: Deploy via SFTP
        uses: presslabs/sftp-action@v1
        with:
          host: ${{ secrets.SFTP_HOST }}
          username: ${{ secrets.SFTP_USER }}
          password: ${{ secrets.SFTP_PASS }}
          localDir: 'wp-content/themes/my-theme'
          remoteDir: '/public_html/wp-content/themes/my-theme'

🧠 Pro Tip: Store SFTP credentials as secrets in your GitHub repo — never hard-code them!

🧪 Strategy 4: Deploying with Capistrano or Deployer (Advanced)

Advanced users may want full control over deployment logic with PHP or Ruby tools:

Deployer (PHP) – Script your WordPress deployments
Capistrano (Ruby) – Widely used in advanced ops pipelines

These tools handle zero-downtime deployment, rollbacks, and remote command execution. Excellent for agencies and enterprise projects.

📚 Choosing the Right Strategy

Strategy	Best For	Automation	Setup Difficulty
Manual FTP	Beginners, one-off changes	❌	Very Easy
Git via Hosting	Freelancers, small teams	✅	Medium
CI/CD Tools	Pro developers, automation lovers	✅✅	Medium–Advanced
Capistrano / Deployer	Agencies, advanced workflows	✅✅✅	Advanced

By integrating Git into your deployment strategy, you reduce mistakes, improve collaboration, and make your development process more professional and future-proof.

🧭 Git Best Practices for WordPress

Version control with Git is incredibly powerful — but it also comes with responsibilities. Following best practices ensures your WordPress project remains clean, stable, and easy to collaborate on over time.

✅ Commit Messages That Make Sense

Good commit messages make your project history readable and useful. Avoid vague entries like:

fix

Instead, prefer something descriptive:

Fix: Resolve broken navigation in mobile view

Tips for writing better commit messages:

Start with a verb (e.g., “Add”, “Fix”, “Update”, “Refactor”)
Be concise, yet clear
Use prefixes if needed (e.g., Theme:, Plugin:)
Group related changes into one commit — avoid committing unrelated fixes together

🧹 Clean .gitignore Files

Always include a .gitignore to avoid tracking sensitive or unnecessary files:

# WordPress core
/wp-admin/
/wp-includes/

# Uploads and cache
wp-content/uploads/
wp-content/cache/

# Environment and OS files
.env
.DS_Store
Thumbs.db

# Dependency directories
node_modules/
vendor/

# Log files
*.log

Note: If you’re only versioning a theme or plugin, tailor the .gitignore accordingly.

🌱 Use Branches Effectively

Branches help organize your work and avoid conflicts:

main or master – stable, production-ready code
develop – ongoing development, merged into main when ready
feature/<name> – for new features or enhancements
hotfix/<name> – for urgent bug fixes on production

🧠 Pro Tip: Never commit directly to main unless it’s a critical patch or you’re working solo on a personal project.

🔍 Review Changes Before Committing

Use git status and git diff before every commit:

git status – shows what’s staged, what’s not
git diff – view the actual code changes

This step helps you catch unwanted changes like temporary debug code, large media files, or the dreaded var_dump().

📥 Don’t Version the Database or Uploads

WordPress’s database and uploads folder change frequently and contain environment-specific or user-generated content. Instead of versioning them, consider:

Using .gitignore to exclude them
Backing them up separately
Using tools like WP Migrate or All-in-One WP Migration to sync environments

📄 Use a README.md File

Every theme, plugin, or full-site repo should include a README.md with:

Project overview
Installation instructions
Development setup guide
Deployment process summary

Bonus: Add badges for things like CI status, PHP version compatibility, or license type if public.

🔐 Never Commit Secrets or API Keys

It’s tempting to drop API keys or credentials into your code while debugging — but once committed, they’re in the Git history forever.

Instead:

Use environment variables (e.g., .env) and ignore them via .gitignore
Use tools like git-secrets to scan for sensitive data
If you accidentally commit secrets, rotate them immediately and remove them from Git history using git filter-repo or git rebase

🤝 Collaborate with Pull Requests

When working in teams, always use Pull Requests (PRs) or Merge Requests (MRs) to:

Review code collaboratively
Catch bugs and enforce standards before merging
Document why a change was made

Most platforms (GitHub, GitLab, Bitbucket) allow inline code comments and approvals before merging.

📦 Working with Composer and Git (Advanced)

Composer is PHP’s dependency manager — and when used with Git in WordPress projects, it introduces a new level of modularity, control, and professionalism. This section explores how to integrate Composer into your Git workflow, especially for managing plugins, themes, and third-party libraries.

🤔 Why Use Composer with WordPress?

Composer allows you to:

Manage plugin and theme dependencies in composer.json
Lock dependencies to specific versions
Keep your vendor directory out of version control
Ensure your team and deployments use the exact same code

🔧 Use Case: Need to install a specific plugin version without downloading a ZIP or adding it to Git? Composer does it cleanly.

🧰 Typical Project Structure with Composer

A Composer-managed WordPress setup may look like:

my-wordpress-site/
├── composer.json
├── composer.lock
├── wp/
│   └── wp-config.php
├── wp-content/
│   ├── themes/
│   └── plugins/
├── vendor/ (ignored)
└── .gitignore

Note: WordPress core can be installed in a subfolder (e.g., wp/) via Composer, using tools like johnpbloch/wordpress.

📝 Sample `composer.json`

{
  "name": "my-site/wordpress",
  "type": "project",
  "require": {
    "johnpbloch/wordpress": "^6.5",
    "wpackagist-plugin/wordpress-seo": "^21.0",
    "wpackagist-theme/twentytwentyfour": "*"
  },
  "extra": {
    "wordpress-install-dir": "wp"
  },
  "repositories": [
    {
      "type": "composer",
      "url": "https://wpackagist.org"
    }
  ],
  "config": {
    "preferred-install": "dist"
  }
}

Highlights:

johnpbloch/wordpress installs WordPress core as a dependency
wpackagist-plugin and wpackagist-theme allow you to install plugins/themes from the WordPress.org repo via Composer

🔒 Commit the Lock File, Not the Vendor Folder

Your composer.lock file records exact dependency versions. Commit this file, so everyone using the repo gets the same environment.

Update your .gitignore like so:

# Composer
/vendor/
composer.lock

✅ Best practice: Commit composer.lock, but ignore /vendor/. Each environment runs composer install to regenerate dependencies.

💡 Using Composer with Bedrock (Optional)

Bedrock is a modern WordPress boilerplate that uses Composer, environment configs, and better folder structures. It’s ideal for advanced users or agencies.

Separates WordPress core from project code
Manages plugins/themes as Composer packages
Provides secure, 12-factor-style configuration

If you’re comfortable with Composer and Git, exploring Bedrock is highly recommended.

🔁 Composer and Git in the Workflow

How does Composer fit into your Git flow?

Install dependencies: composer require vendor/package
Test everything locally
Commit changes to composer.json and composer.lock
Push to Git
Run composer install on staging or production to install dependencies

📌 Version Pinning & Dependency Control

You can control the exact versions of plugins/themes/libraries:

"^2.0" – any minor version update under 3.0
"~2.4.1" – locks to patch updates like 2.4.x
"2.4.3" – exact version

This makes rolling back or reproducing environments far easier than tracking ZIP installs in Git.

🛠️ CI/CD with Composer

In automated deployments, your server or CI/CD pipeline should:

git clone your-repo.git
composer install --no-dev --optimize-autoloader

Some teams cache the vendor folder between builds for speed, but it should not be committed to Git.

🚧 Common Pitfalls and How to Avoid Them

Even seasoned developers can run into trouble when managing WordPress projects with Git. In this section, we’ll explore frequent mistakes and how to prevent them — saving you time, frustration, and cleanup work down the road.

1. Committing the Entire WordPress Core

Problem: Including wp-admin and wp-includes in your repo leads to bloat, merge conflicts during updates, and difficulty managing deployments.

Solution:

Version only your theme, plugin, or a structured install (e.g., using wp/ as the WordPress core folder)
Add core folders to .gitignore
Use Composer to install WordPress core instead of tracking it manually

2. Tracking `wp-content/uploads/`

Problem: Uploads change constantly and don’t belong in version control. Committing them bloats your repo and causes conflicts in collaborative projects.

Solution:

Add wp-content/uploads/ to your .gitignore
Use separate storage (e.g., S3, CDN, shared dev environment)
Share media assets via a backup tool or dedicated media sync plugin

3. Committing Environment-Specific Files

Problem: Files like wp-config.php, .env, and local-config.php often contain credentials and environment-specific settings. Committing them can expose sensitive data or break deployments.

Solution:

Exclude environment files in .gitignore
Use example files (e.g., .env.example) as safe templates
Handle config differences with conditionals or deployment scripts

4. Not Using Branches

Problem: Working on the main branch for all development increases the risk of breaking production code and makes collaboration harder.

Solution:

Create a develop branch for ongoing work
Use feature branches (feature/my-new-widget) for each new task or fix
Merge into main only after review and testing

5. Large or Messy Commits

Problem: Huge commits with unrelated changes are hard to review, debug, and revert.

Solution:

Commit in logical units — one change per commit (e.g., fix a bug, add a feature)
Write clear, informative commit messages
Use git add -p to stage only the changes you want

6. Committing Secrets or API Keys

Problem: Once a secret is committed, it’s permanently stored in your Git history — even if you delete it in a later commit.

Solution:

Use environment variables and .env files
Scan for secrets using tools like git-secrets or Gitleaks
If a secret is committed, revoke and rotate it immediately

7. Ignoring `.gitignore` Hygiene

Problem: A messy or incomplete .gitignore leads to tracking of files you shouldn’t (like node_modules, log files, or IDE settings).

Solution:

Maintain a project-specific .gitignore
Start with a template (e.g., from github/gitignore)
Be mindful of new directories or build tools that may need ignoring

8. Not Using `composer.lock` in Composer Projects

Problem: Without committing composer.lock, dependencies may differ across environments, leading to bugs or inconsistencies.

Solution:

Always commit composer.lock for any project using Composer
Use composer install instead of update in production

9. Force Pushing to Shared Branches

Problem: git push --force on shared branches can rewrite history, destroy teammates’ work, and wreak havoc in CI pipelines.

Solution:

Use --force-with-lease only when absolutely necessary
Avoid force-pushing to main or develop branches
Communicate with your team before rewriting history

10. Neglecting Backups Outside of Git

Problem: Git doesn’t track your database or uploads — if you lose them, Git can’t restore them.

Solution:

Use regular backups for your database and media
Consider tools like WP Migrate, WP-CLI, or BackWPup
Document your backup strategy in your README.md

By proactively addressing these common mistakes, you’ll maintain a cleaner Git history, reduce production risks, and ensure a more collaborative and professional development environment for your WordPress projects.

👉 Next up: Collaboration & Team Workflows with Git

🏁 Conclusion

Using Git with WordPress might seem overwhelming at first — especially if you’re coming from the traditional “edit live on the server” approach. But once you’ve taken the leap, the benefits are undeniable: safer changes, cleaner collaboration, powerful version tracking, and smoother deployments.

This guide has walked you through everything from basic Git setup to advanced tools like Composer, best practices, and the common mistakes to avoid. Whether you’re freelancing, building a team workflow, or scaling up in an agency environment, Git empowers you to treat your WordPress projects like the professional software they are.

Here’s what to take with you:

Version control is not just for core code — it’s for your themes, plugins, config, and more.
Keep your Git history clean and focused. Make small, purposeful commits.
Ignore what needs ignoring: uploads, secrets, local configs, and build files.
Use branches and workflows to organize teamwork and deployment paths.
Composer can make your life easier — even if it takes time to adopt fully.

Ultimately, the real value of Git isn’t just technical — it’s about trust: trusting your code, your teammates, and your future self. With Git in your toolkit, your WordPress development becomes more confident, resilient, and scalable.

👋 Thanks for following along. Happy versioning, and may your commits always be meaningful!

🚀 What This Guide Is About

🧑‍💻 Who This Guide Is For

🧱 Why Git + WordPress Makes Sense

📌 What You’ll Need

🎯 Final Thought Before We Begin…

🔍 Understanding Version Control & Git

📦 What Is Version Control?

🐙 What Is Git?

Why Git Stands Out:

💡 Git vs. No Git: A Workflow Comparison

🧰 Key Git Concepts to Know

🌍 Why WordPress Developers Should Care

🧱 Understanding the WordPress File Structure

🗂️ What’s Inside a Typical WordPress Directory

✅ What You Should Track with Git

🚫 What You Should Ignore in Git

🧭 Common Folder Overview

🔒 A Word on wp-config.php

🎯 Summary

🚀 Setting Up Git for WordPress

🛠️ Prerequisites

📁 Step 1: Navigate to Your Project Folder

🧱 Step 2: Initialize Git

🚫 Step 3: Create a .gitignore File

📸 Step 4: Stage and Commit Your Code

🌐 Step 5: Connect to a Remote Repository (Optional)

🔁 Bonus: Clone a WordPress Git Repo

🔄 Git Workflow for WordPress Projects

🌳 Step 1: Use Branches for Features and Fixes

💾 Step 2: Make Frequent, Clear Commits

📥 Step 3: Pull Often When Working with Others

📤 Step 4: Push Your Work Regularly

🛠️ Optional: Use Pull Requests (or Merge Requests)

♻️ Step 5: Rolling Back Mistakes

🚦 Example Workflow Summary

🧪 Git in Local WordPress Development

🖥️ Common Local Development Tools

📁 Recommended Local Git Project Structure

Option 1: Track the Entire WordPress Project

Option 2: Track Only Your Theme or Plugin

🧪 Working Locally with Git: Daily Tasks

🔗 Bonus: Link Git Repo to Deployment Tools

📁 Example: Using Git with Local by Flywheel

🚀 Git and Deployment Strategies

📦 What Should You Deploy?

📤 Strategy 1: Manual FTP/SFTP Deployment (Baseline)

⚙️ Strategy 2: Git-Based Deployment via Host Integration

🤖 Strategy 3: Automated Deployment Tools

🧪 Strategy 4: Deploying with Capistrano or Deployer (Advanced)

📚 Choosing the Right Strategy

🧭 Git Best Practices for WordPress

✅ Commit Messages That Make Sense

🧹 Clean .gitignore Files

🌱 Use Branches Effectively

🔍 Review Changes Before Committing

📥 Don’t Version the Database or Uploads

📄 Use a README.md File

🔐 Never Commit Secrets or API Keys

🤝 Collaborate with Pull Requests

📦 Working with Composer and Git (Advanced)

🤔 Why Use Composer with WordPress?

🧰 Typical Project Structure with Composer

📝 Sample composer.json

🔒 Commit the Lock File, Not the Vendor Folder

💡 Using Composer with Bedrock (Optional)

🔁 Composer and Git in the Workflow

📌 Version Pinning & Dependency Control

🛠️ CI/CD with Composer

🚧 Common Pitfalls and How to Avoid Them

1. Committing the Entire WordPress Core

2. Tracking wp-content/uploads/

3. Committing Environment-Specific Files

4. Not Using Branches

5. Large or Messy Commits

6. Committing Secrets or API Keys

7. Ignoring .gitignore Hygiene

8. Not Using composer.lock in Composer Projects

9. Force Pushing to Shared Branches

10. Neglecting Backups Outside of Git

🏁 Conclusion

📝 Sample `composer.json`

2. Tracking `wp-content/uploads/`

7. Ignoring `.gitignore` Hygiene

8. Not Using `composer.lock` in Composer Projects