Learn the differences between SCS scopes: ItemAndChildren, ItemAndDescendants, and Ignored to avoid deployment accidents and keep your repository clean.
Front End Developer
Front End Developer
Start typing to search...
Choosing the wrong scope is a common way that developers accidentally break a production environment or bloat their Git repository. Sitecore Content Serialization (SCS) isn't "all or nothing", you have options when it comes to choosing what gets serialized. We'll dive into the difference between ItemAndChildren and ItemAndDescendants (the default value) and discuss which option is best for your specific needs and when to use the Ignored rule. It's important to understand all of the options to avoid deployment accidents which can lead to overwriting content or performance bottlenecks.
You can include scope in either the includes or rules sections of your *.module.json file, depending on the result you are looking for. Use scope inside includes to define the default depth of a serialized path. Use scope inside of rules for more granular control of a path, resulting in exceptions or modifications relating to specific sub-paths. See the code example for ItemAndDescendants below for an example of how to achieve this. Includes is overridden by the rules, and the rules have a first-match-wins approach so the order of the listed scopes is crucial.
ItemAndChildren serializes the parent item and its immediate children only. You would choose this option when you only care about the top-level structure, as it avoids serializing deeply nested unnecessary items. It helps to keep serialization files organized and relevant while excluding unnecessary content.
Performance Impact: High efficiency; it limits the crawler's depth.
Specific Template Sets: When you want to serialize a content item and its immediate children. This helps reduce noise from your repository.
The Risk: Forgetting that "grandchildren" are completely ignored, be careful to not exclude important nested folders.
"items": {
"includes": [
{
"name": "data",
"path": "sitecore/content/data",
"scope": "ItemAndChildren"
},
]
}
ItemAndDescendants is the default and most comprehensive scoping option. It is used to capture the root item as well as its entire tree structure (children and grandchildren included). You'll want to choose this option when you're looking to serialize, version control and deploy an entire subtree of items. It ensures the structure remains intact across environments. Since it is the default option it’s not necessary to list it as the scope within the includes property, however it can be useful for clarity’s sake since not everyone will know it’s the default value.
Performance Impact: Can be heavy on large content trees, which can significantly slow down ser pull and ser push operations.
"items": {
"includes": [
{
"name": "content",
"path": "/sitecore/content/home",
"scope": "ItemAndDescendants",
"rules": [
{
"path": "/products/legacy",
"scope": "ignored"
},
{
"path": "/products",
"scope": "ItemAndDescendants",
"allowedPushOperations": "createUpdateAndDelete"
},
{
"path": "*",
"scope": "ignored"
}
]
}
]
}
Templates: You almost always want the entire template tree.
Renderings/Layouts: Ensuring the full component definition is captured.
The Risk: The "Content Overwrite" nightmare. If used on a content node, a developer might accidentally revert a content author's work to an old version stored in Git.
Ignored excludes specific items or entire sub-trees from serialization within the rules object (not valid in includes). Use Ignored sparingly. Although it's simpler to write, it can be less performant because the system must still parse through the ignored items to recognize they should be skipped. For a more detailed description of when to use Ignored vs. SingleItem check out our other blog which goes more in-depth.
"items": {
"includes": [
{
"name": "content",
"path": "/sitecore/content/home",
"rules": [
{
"path": "/products/legacy",
"scope": "ignored"
},
]
}
]
}
There are a number of instances when Ignored would be useful:
Environment-specific data: Items that are only relevant within certain environments (e.g. local developer test items)
Volatile or dynamic content: Content that is frequently changing or generated dynamically (e.g. analytics data, session data)
Large volumes of content: Authorable page content, for example blogs, that are managed via a content pipeline rather than by developers. Ignoring these improves the performance by avoiding unnecessary serialization checks
Legacy or obsolete items: If items are no longer actively used but are still being kept, you can avoid them interfering with current deployment and development processes
Items matched by a broader rule: SCS uses the first-match-wins approach, you can define an ignored rule for a specific sub-path that falls under a general ItemAndDescendants include rule. This will ensure that a specific branch is skipped
| Scope strategy | Depth | Performance | Best for... |
|---|---|---|---|
ItemAndChildren | Single level | Fast | Folders, settings, roots |
ItemAndDescendants | Recursive (full) | Slower | Templates, branch templates, layouts |
Ignored | None | Instant | Protecting content, media, test data |
Scopes are about precision. Use the information above to consider your content tree and project context. You can always run ser pull --whatif before committing your module changes to preview the impact without modifying any data, and remember, put the most specific rule first if you have overlapping rules since the system works by the first-match-wins approach.