In this article you can learn more about how to effectively source control your Umbraco site.
When you are running your site on Umbraco Cloud, source control is a part of the experience. Have a look at the 'Technical overview of an Umbraco Cloud Environment' and the information on 'Working with your Umbraco Cloud project' for a steer on Source/Version Control good practices.
If you are hosting your Umbraco implementation outside of Umbraco Cloud, it's generally considered good practice to set up source/version control for your site implementation files. This is especially a good idea when you are working with a team as it can help you track changes and manage conflicts with other developer's work.
So if you've made the decision to try to attempt to source/version control your Umbraco implementation work, perhaps setting up a 'Git Repository' - then a frequently asked question is:
There are lots of different possible variations within your working environment that will affect the best way to set up version control. It depends on whether you are:
Working with a team of developers.
How your development environment is set up.
Source control repository.
And also how you intend to build and deploy your solution to your target production environment (build servers, Web Deploy or good old File Transfer Protocol (FTP), etc).
However, Umbraco ships with a .gitignore file with a custom Umbraco section, which will make git ignore the files for you. The Umbraco specific section looks like this:
For most projects, this gitignore will be enough, and this article will not be an exhaustive list of how to version control Umbraco in all possible scenarios.
However, we will go through the different files in order to give you an insight into the anatomy of an Umbraco website and therefore which parts to include in version control and which parts not to.
The main folder where the Umbraco CMS resides is the /umbraco one inside your project.
Most of the files and folders within the Umbraco folder, is already added to the default gitignore file. As most of the Umbraco CMS core files are embedded, the /umbraco folder contains primarily temporary files and log files, which are all added as Umbraco is installed.
We recommend that you follow the structure of the default gitignore file, and do not include any temporary files, log files or cache files to git.
Below are a set of general recommendations regarding the files within the /umbraco folder.
/umbraco/data/TEMP - This folder contains examine indexes, NuCache files, and so on, these are temporary and should not be committed.
/umbraco/Logs - Umbraco currently uses Serilog, and a file will be generated in this folder containing trace logs of your application, one JSON file for each day.
/umbraco/mediacache - ImageSharp ships with Umbraco and when an image is requested via the processor, for example, to be resized or cropped, a cached version of the transformed image will be stored in this folder. (The Imaging settings section allows you to determine where this cache is stored)
The main folder where the Umbraco CMS resides in, is the /umbraco one inside your project.
Some of the contents change when you upgrade Umbraco, and will even be deleted and re-added on a clean and rebuild! No part of your implementation or third-party packages installed should update these folders.
From the gitignore above we can see that the content that will change when you upgrade Umbraco and be deleted and re-added on clean and rebuild are:
umbraco/UmbracoWebsite
umbraco/UmbracoInstall
umbraco/UmbracoBackoffice
umbraco/config/lang
umbraco/config/appsettings-schema.json
None of these folders should be committed to github since they will automatically be added on build. If you're working with an Integrated Development Environment (IDE) and a Build Server, it's NuGet's and MSBuild's job to restore the correct versions of these folders for you. If you don't use an IDE and prefer the command line you can use dotnet restore to manually restore the NuGet packages.
But these are not the only files in the Umbraco folder that you should not commit to your git, some files are generated during runtime and should not be committed either, these are:
/umbraco/data/TEMP - This folder contains examine indexes, NuCache files, and so on, these are temporary and should not be committed.
Umbraco.sdf - If you are using SQL CE for the data store in your Umbraco site, then this file IS that datastore, it will be difficult to source control the constant changes to this file.
/umbraco/Logs - Umbraco currently uses Serilog, and a file will be generated in this folder containing trace logs of your application, one JSON file for each day.
/umbraco/mediacache - ImageSharp ships with Umbraco and when an image is requested via the processor, for example, to be resized or cropped, a cached version of the transformed image will be stored in this folder. (The Imaging settings section allows you to determine where this cache is stored)
We've now covered most of the folders within the /umbraco folder, however, there are two left, the /umbraco/models folder, and the /umbraco/PartialViewMacros. The model's folder has its own section right below, but for the PartialViewMacros folder, the answer to "should I commit this to git" is that it depends. If you want to change the templates within the folder or add your own, then you should commit it to git, if you don't need to do that, you should not, the build will automatically create it and its content.
The Umbraco wwwroot folder
The /wwwroot/umbraco folder contains static assets for the backoffice, these files will be automatically created when you do a build, and should not be included in source control.
The strategy here will depend a little on which mode 'Umbraco Models Builder' you have opted to work with.
InMemoryAuto (default), The models are generated in memory, no source control is required.
SourceCodeManual and SourceCodeAuto, The models are generated in the /umbraco/models folder of your project (or can be configured to be in a different folder or project), allowing you to track changes to the models in source/version control.
The Media section of Umbraco (unless configured otherwise) stores files in the /wwwroot/media folder. These can be updated by editors, in the Umbraco backoffice, so generally speaking, you would not source control these files.
These are by default ignored by git.
The App_Plugins folder is the home for all third-party packages installed on your site.
Depending on how you installed the plugin it will affect how you choose to version control a particular third-party plugin:
Since plugins are installed via NuGet the installed files for individual plugins shouldn't need to be source controlled (and your deployment process should pull the packages implementation files from NuGet during the build and deployment process).
Each plugin could be different depending on its implementation and functionality. It may contain files that it would be useful to track via Source control, and also files that should be ignored: check with the plugin's supporting website/developer for more information.
A lot depends on how you maintain the front-end build of your website, e.g. are you using CSS preprocessors such as Sassy Cascading Style Sheets (SCSS)/ Leaner CSS (LESS) etc - gulp/grunt tasks to combine and minify script resources.
But generally, you will need to source control all your website's static assets: JavaScript, CSS, Fonts, Page Furniture Images, etc.
Umbraco site templates/views can be edited via the Umbraco Backoffice. They also reside in the /Views folder on disk. As these views/templates often include code, it can make a lot of sense to have their changes tracked under source/version control.
However, this can pose a problem if the templates are updated via the backoffice outside of source control on the production environment.
This is not an advisable approach since often this will cause breaking changes to your website.
You would need to manually merge these files before considering a deployment.
Umbraco Cloud is a good solution in these scenarios, as changes via the backoffice are tracked in a Git repository automatically.
To source/version control changes to Macro implementation code, track the files in the following location:
Partial View Macros - stored in /Views/MacroPartials as .cshtml files
Any supporting custom code for your application should be in version control, eg any of the following files
C# implementation,
Surface Controllers
API Controllers
ViewModels
Helpers / Extension Methods
Services etc.
Supporting class library projects,
Models generated by Modelsbuilder in SourceCodeManual or SourceCodeAuto mode.
Your site's appsettings.json and appsettings.Development.json files contain the configuration for your Umbraco site.
In general, it is recommended to add these to source control. When you do this, be sure that the file(s) doesn't contain any secrets, like API keys and connection strings. These can be added as needed, but omitted from any commits made to source control.
When you create and edit eg. Document Types, Media Types, and Data Types in the Umbraco Backoffice these values are stored in the Umbraco Database, making them difficult to source control in a 'file based' version control system.
There are a series of add-on packages that can help add source control to these structure changes:
The uSync package (free) - which can be configured to serialize these changes to files on disk, in a folder called /uSync - enabling you to source/version control these changes and synchronise them to other environments.
uSync Snapshots (licensed) - an extension to uSync, for taking 'before' and 'after' snapshots of an Umbraco site, for managing a release of a 'set of changes' between environments.
Umbraco Deploy on Premise - the on premise version of the package used by Umbraco Cloud.