Compare-Object
Compares two sets of objects.
Syntax
Default (Default)
Compare-Object
[-ReferenceObject] <PSObject[]>
[-DifferenceObject] <PSObject[]>
[-SyncWindow <Int32>]
[-Property <Object[]>]
[-ExcludeDifferent]
[-IncludeEqual]
[-PassThru]
[-Culture <String>]
[-CaseSensitive]
[<CommonParameters>]
Description
The Compare-Object cmdlet compares two sets of objects. One set of objects is the reference,
and the other set of objects is the difference.
Compare-Object checks for available methods of comparing a whole object. If it can't find a
suitable method, it calls the ToString() methods of the input objects and compares the string
results. You can provide one or more properties to be used for comparison. When properties are
provided, the cmdlet compares the values of those properties only.
The result of the comparison indicates whether a property value appeared only in the reference
object (<=) or only in the difference object (=>). If the IncludeEqual parameter is
used, (==) indicates the value is in both objects.
If the reference or the difference objects are null ($null), Compare-Object generates a
terminating error.
Some examples use splatting to reduce the line length of the code samples. For more information, see about_Splatting.
Parameters
-CaseSensitive
Indicates that comparisons should be case-sensitive.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Culture
Specifies the culture to use for comparisons.
Parameter properties
| Type: | String |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-DifferenceObject
Specifies the objects that are compared to the reference objects.
Parameter properties
| Type: | PSObject[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 1 |
| Mandatory: | True |
| Value from pipeline: | True |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ExcludeDifferent
Indicates that this cmdlet displays only the characteristics of compared objects that are equal. The differences between the objects are discarded.
Use ExcludeDifferent with IncludeEqual to display only the lines that match between the reference and difference objects.
If ExcludeDifferent is specified without IncludeEqual, there's no output.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-IncludeEqual
IncludeEqual displays the matches between the reference and difference objects.
By default, the output also includes the differences between the reference and difference objects.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-PassThru
When you use the PassThru parameter, Compare-Object omits the PSCustomObject wrapper
around the compared objects and returns the differing objects, unchanged.
Parameter properties
| Type: | SwitchParameter |
| Default value: | False |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-Property
Specifies an array of properties of the reference and difference objects to compare.
The value of the Property parameter can be a new calculated property. The calculated property can be a script block or a hash table. Valid key-value pairs are:
- Expression -
<string>or<script block>
For more information, see about_Calculated_Properties.
Parameter properties
| Type: | Object[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-ReferenceObject
Specifies an array of objects used as a reference for comparison.
Parameter properties
| Type: | PSObject[] |
| Default value: | None |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | 0 |
| Mandatory: | True |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
-SyncWindow
Specifies the number of adjacent objects that Compare-Object inspects while looking for a match in
a collection of objects. Compare-Object examines adjacent objects when it doesn't find the object
in the same position in a collection. The default value is [Int32]::MaxValue, which means that
Compare-Object examines the entire object collection.
Parameter properties
| Type: | Int32 |
| Default value: | [Int32]::MaxValue |
| Supports wildcards: | False |
| DontShow: | False |
Parameter sets
(All)
| Position: | Named |
| Mandatory: | False |
| Value from pipeline: | False |
| Value from pipeline by property name: | False |
| Value from remaining arguments: | False |
CommonParameters
This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutBuffer, -OutVariable, -PipelineVariable, -ProgressAction, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.
Inputs
PSObject
You can send an object down the pipeline to the DifferenceObject parameter.
Outputs
None
If the reference object and the difference object are the same, there's no output, unless you use the IncludeEqual parameter.
PSCustomObject
If the objects are different, Compare-Object wraps the differing objects in a PSCustomObject
wrapper with a SideIndicator property to reference the differences.
When you use the PassThru parameter, the Type of the object is not changed but the instance of the object returned has an added NoteProperty named SideIndicator. SideIndicator shows which input object the output belongs to.
Notes
When using the PassThru parameter, the output displayed in the console may not include the
SideIndicator property. The default format view of the for the object type output by
Compare-Object does not include the SideIndicator property. For more information see
Example 3 in this article.