Most developers have found Git an integral tool when working on any software development project, large or small. This version control system helps keep track of all code changes and creates an effective environment for the team to work on the same project simultaneously.
However, as the project grows, keeping the repository clean and tidy with thousands of files becomes difficult. And here’s where the gitignore file comes into play.
Generally, the .gitignore config allows you to specify the files and folders you do not want to add to the Git repository. These may include temporary and test files, logs, backups, copies of Magneto files, or folders specific to your environment.
This tutorial describes a workflow for skipping unnecessary files and folders while storing the Magento 2 eCommerce platform in the Git repository. Please note that due to common rules, these instructions apply to any other system.
Magento 2 Gitignore File Example
In the Magento 2 project, the gitignore file is placed in the Magento root directory. Here’s an example of what the .gitignore file format can look like:
# Ignore all folders/files inside the /vendor folder, except /vendor/.htaccess/vendor/*!/vendor/.htaccess# Ignore the package.json file inside the root directory /package.json# Skip all ZIP archives in the Magento 2 root directory or any subdirectories*.zipHere are some key points about .gitignore file format:
- Lines starting with “#” are comments and ignored by Git.
- You can use wildcards like “*” to match multiple characters and “?” for a single character. For example, a line *.txt would ignore all files ending with “.txt”.
- To ignore entire directories, add a forward slash “/” at the end of the pattern.
How to Optimize Magento 2 Gitignore File
Prerequires:
- Git tool, installed on your server or computer
- Repository, where you plan to store the files (e.g., GitHub, GitLab, BitBucket)
- SSH connection in case you work remotely with the server
- Full backup of the Magento 2 files
Step #1. Clean Unnecessary Magento files
Before you add the Magento files to Git, it’s important to remove unnecessary files, especially if they are big or contain sensitive data. These files may include:
- Temporary and test files (e.g., test.php, phpinfo.php, adminer.php)
- Backups (e.g., “files.zip”, “db-dump.sql”, “*.php-bak” files, and so on)
- Logs outside of the “var” directory
- Copies of Magento files and folders. For example, sometimes, you can find a copy of the “app/etc/env.php” file or “pub/media” folder
- Other unused garbage
Step #2. Enhance default Magento .gitignore file
Magento 2 contains the .gitignore out of the box. Here you can find the latest Magento Open Source gitignore file and see what’s included. It typically covers the most common files you wouldn’t want to track in your Git repository, for example:
- Composer “vendor” folder
- Catalog images and others under the “pub/media” directory
- Caches, logs, and autogenerated files (/var/, /generated/, /pub/static/*)
- app/etc/env.php file, which contains sensitive data (e.g., database password)
However, your project-specific files must be manually added to Magento 2 gitignore to prevent any sensitive information about your custom modules or themes from being included in your repository.
Please follow the 4 tips below to enhance and optimize your Magento 2 gitignore file.
1. Add more formats
# Packages*.7z*.dmg*.gz*.iso*.jar*.rar*.tar*.zip*.tgz*.tar.gz# Logs and databaseslog/*.log*.sql*.sqlite# OS generated files.DS_Store.DS_Store?ehthumbs.dbIcon?Thumbs.db._*.Spotlight-V100.Trashes# Exclude IDEs directories.ideanbproject2. Move subsystems to separate repositories
Sometimes, additional systems can be installed together with the Magento store. For example, a WordPress CMS can be installed in the “blog” subfolder.
In this case, we recommend storing the Magento and WordPress files in separate Git repositories. Therefore, you should add the “/blog” folder to the Magento .gitignore file.
3. Add large files
To ensure the efficient performance of repositories, Github imposes limitations related to file size and blocks files larger than 100 MB. In order to prevent issues with pushing or pulling changes due to oversized files, you should add them to the gitignore file.
To find and download the list of large files, you can use the following command:
find . -size +100M | cat >> large-files.txtAdditionally, it makes sense to review small files in the same way (e.g., 50MB or even 10MB). It can help you exclude unnecessary from Git.
If you need to check the list of the largest folders and files, use the following command:
du -sh ./* | sort -h4. Add autogenerated files
The base gitignore file, which is included in the Magento 2 root directory by default, already ignores standard autogenerated files, such as /var/, /generated/, /pub/static/*, etc.
However, your custom code or third-party extensions can also automatically generate some files. These include data feeds, exports, resized images, combined CSS/JS assets, backups, sitemaps, etc. It is recommended to ignore such files to optimize your repository performance.
Step #3. Check files that will be added to the commit
The git status command displays files ready to be added and pushed to the Git repository. If the list of files is huge, it is recommended to save an output to the file using the command below and review the list.
git status > git-files.txtRepeat the previous steps (#1 and #2) if the list still contains unnecessary files.
Step #4. Add an exception in composer.json
When you update Magento or set up a fresh dev copy, you run the following command:
composer installThis command downloads the PHP libraries (dependencies) into the /vendor folder. During execution, it overrides Magento files in the root directory (e.g., .gitignore, .htacess, index.php, etc.).
To prevent overriding and thus removing all changes you have made to the .gitignore file, add the following command in the “composer.json” config:
"extra": { "magento-force": "override", "magento-deploy-ignore": { "*": [ "/.gitignore" ] }},Step #5. Add files to gitignore
Finally, you can proceed with the standard Git workflow – add and commit files and push them to the Github repository.
Conclusion
Git is the necessary version control system for software developers, and keeping it clean of unnecessary files helps maintain its high performance and efficiency for future development and collaborations.
Although Magento 2 gitignore file is included by default, it’s important to optimize it and tailor it to your specific project. It excludes the most common files from tracking in your Git repository but doesn’t cover files generated by your custom theme or extension.
Using tips from this tutorial, you will optimize the default Magento 2 gitignore by adding your project-specific, large, auto-generated, and other files that should be excluded from tracking in your Git repository. This will result in a much cleaner Magento 2 store, optimize your current workflow, and facilitate future development. So, don’t hesitate to implement these best practices to enjoy a more efficient development process.
P.S. GitHub has prepared a collection of useful .gitignore templates for many systems (including Magento, WordPress, Joomla, Laravel framework, etc.): https://github.com/github/gitignore
