How to organize a Magento 2 repository on GitHub

When creating a Magento 2 instance, there are many folders and files in the installation directory, this guide can help you understand which files should be added to your project's repository and which ones are not needed or could even be problematic to include. 

Efficient Magento 2 development requires not only good programming practices, but also proper version control management and collaborative workflows. One of the most effective tools to achieve this is GitHub, a platform that allows you to manage code, track changes and maintain order in complex projects. Having a well-organized repository is essential to ensure scalability, clarity and team productivity when working with Magento-based solutions.

Magento 2 projects often include multiple modules, custom themes, third-party extensions and configuration files, which can make management difficult if there is no clear repository structure. Defining conventions for branches, pull requests and documentation allows development teams to work in a more orderly fashion and avoid unnecessary conflicts.


This article presents best practices for organizing a GitHub repository in Magento 2 projects, addressing folder structure, branching strategies, and documentation recommendations. Implementing a consistent and scalable repository organization facilitates collaboration, minimizes errors, and ensures high code quality throughout the project lifecycle.

It will also explain in broad terms how the Magento filesystem works and what recommendations are used to optimize your repository. For an ideal understanding of this article, it is recommended to have a basic understanding of Git and GitHub (or some equivalent tool like GitLab or BitBucket), however the concepts below are useful for anyone who wants to learn about files and folders in a Magento 2 project.

First of all, let's list the default Magento 2.4 repository:

• composer.json: this file contains the information of the modules and their dependencies of the project.
  
  
• composer.lock: this file specifies the exact versions of the components in the project.
  
  
• .htaccess, pub/.htaccess, pub/media.htaccess y pub/static/.htaccess: these files contain header and directive information for the server to execute.
  
  
• .gitignore: this file contains the specifications of all the files and directories that should not be included in the git repository, either because they are files generated in the build process or they consume unnecessary space in the repository.
  
  

The above files must always be included in our repository, but in addition, the following files or directories may also be included:

• app/code: this is where the project modules that were not installed using Composer are located.
  
  
• app/design: themes for frontend and admin site.
  
  
• app/etc: this folder contains project settings and variables. These files can be useful in the repository to have as a backup, but it is important to take into consideration that there are files in this directory with sensitive or confidential data, in particular the app/etc/env.php file, which contains credentials to access the database and access to the administrative site. This folder should only be included in the repository if it is private and only accessible to authorized people.
  
  
• pub/media: this folder contains the images of the catalog, media files and other types of public documents such as PDFs or videos. Because of this, they are often excluded from the repository due to storage limitations provided by remote repositories like GitHub. For the storage of these files, it is recommended to use services such as Google Drive, Dropbox, AWS S3, etc.
  
  

Files and folders to avoid adding to the repository (must be in the .gitignore file):

• pub/static (except .htaccess): here are the static files generated in the setup:static-content:deploy process, so uploading them to the repository is unnecessary.
  
  
• generated: the contents of this folder are auto-generated in the site build process, so there is no reason to add them to the repository.
  
  
• var: the contents of this folder are often temporary or for recording logs and reports. It may be useful to back up this folder but it is recommended to use a dedicated storage service as they can be large and volatile so it is not recommended to add them to the repository.
  
  
• vendor: the content of this folder should not be modified manually, only with composer, so adding the composer.json and composer.lock files are enough to determine the content of the vendor directory, without the need to add the code itself. Any modifications to the vendor files will likely be overwritten when upgrading Magento.
  
  
• lib: here are libraries used in modules and components, it might be necessary to add it to the repository, but it is recommended to use composer for the orchestration of the libraries, in which case, as with the vendor folder, it is not necessary to add the code itself.
  
  
  
  
  >> How to configure the wishlist in Magento <<
  
  
  

Finally, the following recommendations can make it easier to manage the code and resources of the repository and avoid errors:

• Use branches for each modification: creating a branch is quick and easy, not to mention that it allows you to control versions, perform integration tests and analyze modifications easily... and of course, avoid uploading bugs to the master branch.
  
  
• Maintain consistency between the development and production (or other) environments, as it's common that over time, the different environments start to accumulate discrepancies, since they are not in the same commits or versions of the repository, and may contain a lot of test products, sections or accounts. When there are many inconsistencies between environments, it is a sign of bad development practices, since it's important to have environments that are as identical as possible to carry out accurate tests and modifications. This development and deployment procedure is relevant to the field of DevOps, which is used to streamline development, integration and testing processes, and reduce possible errors.
  
  
• Add a README.md file: this file is merely to explain the nature and content of the repository, it is to help new contributors or viewers to understand and use the code effectively.
  
  
• Write meaningful commit messages: avoid generic commits such as "bugfix" or "version X changes", as they do not allow other people to understand or identify the purpose of the change at a glance. Also, we all forget a some things over time, so take a few extra seconds to write clear and meaningful messages every time you commit.
  
  

I hope this article has been useful to understand how to organize a GitHub repository in Magento 2, remember that all projects are different and there are no definitive rules of what you can add and what not, however if you apply the concepts explained above, you can avoid various problems on the way and work more orderly and safely.