This project has moved and is read-only. For the latest updates, please go here.

Fleshing out the documentation on codeplex

Mar 3, 2014 at 12:06 PM
Hi guys,

First of all: excellent tool, I've tested it and love it so far.

One thing though: the documentation in PS is far more extensive than what is displayed under the documentation tab on codeplex. Having that information available here would probably be very helpful; speaking for myself I like to know just what it is I bolt onto my farm before I install it.


This cmdlet is used to selectively remove backup sets from a backup catalog - a process known as "grooming." This permits retention of backup sets based on a count or size limit, and it prevents a backup catalog from growing over time to consume all storage available to it.

Remove-SPBackupCatalog [-EntireCatalog <SwitchParameter>] [-Identity] <SPBackupCatalogPipeBind> [-IgnoreBackupSetErrors <SwitchParameter>] [[-RetainCount] <Int32>] [[-RetainSize] <Int64>] [-AssignmentCollection <SPAssignmentCollection>] [<CommonParameters>]

This cmdlet is used to selectively remove backup sets from a backup catalog - a process known as "grooming." This permits retention of backup sets based on a count or size limit, and it prevents a backup catalog from growing over time to consume all storage available to it.

Copyright (C) 2011 Sean P. McDonough. Use of these cmdlets is at your own risk. Sean P. McDonough assumes no liability. For more information on the SharePoint 2010 Backup Augmentation Cmdlets, see

-EntireCatalog [<SwitchParameter>]
    Specifying this switch results in the complete deletion of all data in the backup catalog. When this switch is specified, the -RetainCount and -RetainSize parameters have no effect.

-Identity <SPBackupCatalogPipeBind>
    The backup catalog which will serve as the target for operations. This can be specified as an existing SPBackupCatalog object or as a path to the target backup catalog root (i.e., where the spbrtoc.xml resides).

-IgnoreBackupSetErrors [<SwitchParameter>]
    When -RetainCount and -RetainSize calculations are performed, they don't include backup sets that have errors. This is to avoid scenarios where backup grooming may remove good backup sets (i.e., those without errors) and leave only bad backup sets behind. If the -IgnoreBackupSetErrors switch
     is specified, then -RetainCount and -RetainSize calculation don't distinguish between backup sets with errors and those without. Use of this switch should be considered carefully, as it could leave you in a situation where your backup catalog contains only bad backups that are non-restorabl

-RetainCount [<Int32>]
    The maximum number of non error-containing full backup sets to retain. When this parameter is specified, only content+configuration full-mode backups are counted for purposes of retention. Configuration-only backups are ignored for purposes of grooming, but they will be groomed-out if they a
    re older than the last full backup to be retained. Differential backups are associated with their full backup for retention purposes. Even though they aren't included in the backup set count, differential backups are groomed-out or retained according to what happens with their full-mode base
     backup set.

-RetainSize [<Int64>]
    The maximum size, in bytes, of non error-containing backup sets to be retained. When this parameter is specified, it will groom a backup catalog to the specified size or below. Since this grooming typically occurs after backups have been performed, it obviously cannot permit backup catalogs 
    from growing to a size greater than the -RetainSize; it simply trims the backup catalogs down after-the-fact.

-AssignmentCollection [<SPAssignmentCollection>]
    Manages objects for the purpose of proper disposal. Use of objects, such as SPWeb or SPSite, can use large amounts of memory and use of these objects in Windows PowerShell scripts requires proper memory management. Using the SPAssignment object, you can assign objects to a variable and dispo
    se of the objects after they are needed to free up memory. When SPWeb, SPSite, or SPSiteAdministration objects are used, the objects are automatically disposed of if an assignment collection or the Global parameter is not used.

    When the Global parameter is used, all objects are contained in the global store. If objects are not immediately used, or disposed of by using the Stop-SPAssignment command, an out-of-memory scenario can occur.

    This cmdlet supports the common parameters: Verbose, Debug,
    ErrorAction, ErrorVariable, WarningAction, WarningVariable,
    OutBuffer and OutVariable. For more information, see 
    about_CommonParameters ( 

------------------EXAMPLE 1-----------------------

Remove-SPBackupCatalog \\SPFarmShare\Backups -RetainCount 5 -RetainSize 20GB

This example combines both a -RetainCount and -RetainSize to groom backups to a fixed full backup count and size. The backup catalog is first trimmed down to five full-mode non error-containing backups and any differential backups that depend on those full-mode backups. After being groomed to fi
ve full-mode backups, the backup catalog is further trimmed (if necessary) to get its size to 20GB or less based on remaining non error-containing backup sets.
------------------EXAMPLE 2-----------------------

Remove-SPBackupCatalog \\SPFarmShare\Backups -EntireCatalog

In this example, all backup data is deleted from the catalog that is targeted. An spbrtoc.xml file remains in the catalog location, and it continues to reflect restore and non-backup operations, but all backup set data in the location is deleted. This frees the maximum amount of disk space. Note
 that if this switch is specified, the -RetainCount and -RetainSize parameters have no effect.
------------------EXAMPLE 3-----------------------

Remove-SPBackupCatalog \\SPFarmShare\Backups -RetainCount 1 -IgnoreBackupSetErrors

In this example, all backup sets save for the most recent one are deleted. The -IgnoreBackupSetErrors means that any backup set errors will be ignored during the grooming process. Even if the most recent backup set contains errors, it will be the only backup set that is retained following execut
ion of this command. This illustrates why use of the -IngoreBackupSetErrors switch should be considered carefully; it could leave you without a viable backup from which to restore.
------------------EXAMPLE 4-----------------------

Remove-SPBackupCatalog \\SPFarmShare\Backups -RetainCount 3

In this example, all backups in the catalog located at \\SPFarmShare\Backup are deleted save for the last three non error-containing full-mode backups (-RetainCount 3) and any differential backups that depend on them. Any restores that were performed remain in the backup catalog; only backup set
s/folders are deleted.
------------------EXAMPLE 5-----------------------

Get-SPBackupCatalog \\SPFarmShare\Backups | Remove-SPBackupCatalog -RetainSize 10GB

In this example, an SPBackupCatalog object is created and piped to the Remove-SPBackupCatalog cmdlet with a -RetainSize of 10GB specified. The cmdlet then examines the backup catalog; if it finds that the catalog is larger than 10GB in size, it will delete the oldest full backup set, any differe
ntial backups that depend on the full backup, and any configuration-only backups that took place prior to the next-oldest full-mode backup. The cmdlet then re-examines the size of the backup catalog and repeats the process until the backup catalog is equal to or less than 10GB in size. Note that
 by default, only non error-containing backup sets are considered during size calculations to avoid a situation where all viable backup sets are groomed-out. To avoid this behavior, use the -IgnoreBackupSetErrors switch.
To see the examples, type: "get-help Remove-SPBackupCatalog -examples".
For more information, type: "get-help Remove-SPBackupCatalog -detailed".
For technical information, type: "get-help Remove-SPBackupCatalog -full".
For online help, type: "get-help Remove-SPBackupCatalog -online"