- Reference
- Module:
- Microsoft.PowerShell.Utility
Compares two sets of objects.
Syntax
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 asuitable method, it calls the ToString() methods of the input objects and compares the stringresults. You can provide one or more properties to be used for comparison. When properties areprovided, the cmdlet compares the values of those properties only.
The result of the comparison indicates whether a property value appeared only in the referenceobject (<=) or only in the difference object (=>). If the IncludeEqual parameter isused, (==) indicates the value is in both objects.
If the reference or the difference objects are null ($null), Compare-Object generates aterminating error.
Some examples use splatting to reduce the line length of the code samples. For more information, seeabout_Splatting.
Examples
Example 1 - Compare the content of two text files
This example compares the contents of two text files. The example uses the following two text files,with each value on a separate line.
Testfile1.txtcontains the values: dog, squirrel, and bird.Testfile2.txtcontains the values: cat, bird, and racoon.
The output displays only the lines that are different between the files. Testfile1.txt is thereference object (<=) and Testfile2.txtis the difference object (=>). Lines withcontent that appear in both files aren't displayed.
Compare-Object -ReferenceObject (Get-Content -Path C:\Test\Testfile1.txt) -DifferenceObject (Get-Content -Path C:\Test\Testfile2.txt)InputObject SideIndicator----------- -------------cat =>racoon =>dog <=squirrel <=Example 2 - Compare each line of content and exclude the differences
This example uses the ExcludeDifferent parameter to compare each line ofcontent in two text files.
As of PowerShell 7.1, when using the ExcludeDifferent parameter, IncludeEqual is inferredand the output only contains lines contained in both files, as shown by the SideIndicator(==).
$objects = @{ ReferenceObject = (Get-Content -Path C:\Test\Testfile1.txt) DifferenceObject = (Get-Content -Path C:\Test\Testfile2.txt)}Compare-Object @objects -ExcludeDifferentInputObject SideIndicator----------- -------------bird ==Example 3 - Show the difference when using the PassThru parameter
Normally, Compare-Object returns a PSCustomObject type with the following properties:
- The InputObject being compared
- The SideIndicator property showing which input object the output belongs to
When you use the PassThru parameter, the Type of the object is not changed but the instanceof the object returned has an added NoteProperty named SideIndicator. SideIndicatorshows which input object the output belongs to.
The following examples shows the different output types.
$a = $TrueCompare-Object -IncludeEqual $a $a(Compare-Object -IncludeEqual $a $a) | Get-MemberInputObject SideIndicator----------- ------------- True == TypeName: System.Management.Automation.PSCustomObjectName MemberType Definition---- ---------- ----------Equals Method bool Equals(System.Object obj)GetHashCode Method int GetHashCode()GetType Method type GetType()ToString Method string ToString()InputObject NoteProperty System.Boolean InputObject=TrueSideIndicator NoteProperty string SideIndicator===Compare-Object -IncludeEqual $a $a -PassThru(Compare-Object -IncludeEqual $a $a -PassThru) | Get-MemberTrue TypeName: System.BooleanName MemberType Definition---- ---------- ----------CompareTo Method int CompareTo(System.Object obj), int CompareTo(bool value), int IComparable.CompareTo(SystEquals Method bool Equals(System.Object obj), bool Equals(bool obj), bool IEquatable[bool].Equals(bool otGetHashCode Method int GetHashCode()GetType Method type GetType()GetTypeCode Method System.TypeCode GetTypeCode(), System.TypeCode IConvertible.GetTypeCode()ToBoolean Method bool IConvertible.ToBoolean(System.IFormatProvider provider)ToByte Method byte IConvertible.ToByte(System.IFormatProvider provider)ToChar Method char IConvertible.ToChar(System.IFormatProvider provider)ToDateTime Method datetime IConvertible.ToDateTime(System.IFormatProvider provider)ToDecimal Method decimal IConvertible.ToDecimal(System.IFormatProvider provider)ToDouble Method double IConvertible.ToDouble(System.IFormatProvider provider)ToInt16 Method short IConvertible.ToInt16(System.IFormatProvider provider)ToInt32 Method int IConvertible.ToInt32(System.IFormatProvider provider)ToInt64 Method long IConvertible.ToInt64(System.IFormatProvider provider)ToSByte Method sbyte IConvertible.ToSByte(System.IFormatProvider provider)ToSingle Method float IConvertible.ToSingle(System.IFormatProvider provider)ToString Method string ToString(), string ToString(System.IFormatProvider provider), string IConvertible.ToToType Method System.Object IConvertible.ToType(type conversionType, System.IFormatProvider provider)ToUInt16 Method ushort IConvertible.ToUInt16(System.IFormatProvider provider)ToUInt32 Method uint IConvertible.ToUInt32(System.IFormatProvider provider)ToUInt64 Method ulong IConvertible.ToUInt64(System.IFormatProvider provider)TryFormat Method bool TryFormat(System.Span[char] destination, [ref] int charsWritten)SideIndicator NoteProperty string SideIndicator===When using PassThru, the original object type (System.Boolean) is returned. Note how theoutput displayed by the default format for System.Boolean objects didn't display theSideIndicator property. However, the returned System.Boolean object has the addedNoteProperty.
Example 4 - Compare two simple objects using properties
In this example, we compare two different string that have the same length.
Compare-Object -ReferenceObject 'abc' -DifferenceObject 'xyz' -Property Length -IncludeEqualLength SideIndicator------ ------------- 3 ==Example 5 - Comparing complex objects using properties
This example shows the behavior when comparing complex objects. In this example we store twodifferent process objects for different instances of PowerShell. Both variables contain processobjects with the same name. When the objects are compared without specifying the Propertyparameter, the cmdlet considers the objects to be equal. Notice that the value of theInputObject is the same as the result of the ToString() method. Since theSystem.Diagnostics.Process class does not have the IComparable interface, the cmdletconverts the objects to strings then compares the results.
PS> Get-Process pwsh NPM(K) PM(M) WS(M) CPU(s) Id SI ProcessName ------ ----- ----- ------ -- -- ----------- 101 123.32 139.10 35.81 11168 1 pwsh 89 107.55 66.97 11.44 17600 1 pwshPS> $a = Get-Process -Id 11168PS> $b = Get-Process -Id 17600PS> $a.ToString()System.Diagnostics.Process (pwsh)PS> $b.ToString()System.Diagnostics.Process (pwsh)PS> Compare-Object $a $b -IncludeEqualInputObject SideIndicator----------- -------------System.Diagnostics.Process (pwsh) ==PS> Compare-Object $a $b -Property ProcessName, Id, CPUProcessName Id CPU SideIndicator----------- -- --- -------------pwsh 17600 11.4375 =>pwsh 11168 36.203125 <=When you specify properties to be compared, the cmdlet shows the differences.
Example 6 - Comparing complex objects that implement IComparable
If the object implements IComparable, the cmdlet searches for ways to compare the objects.If theobjects are different types, the Difference object is converted to the type of theReferenceObject then compared.
In this example, we are comparing a string to a TimeSpan object. In the first case, the stringis converted to a TimeSpan so the objects are equal.
Compare-Object ([TimeSpan]"0:0:1") "0:0:1" -IncludeEqualInputObject SideIndicator----------- -------------00:00:01 ==Compare-Object "0:0:1" ([TimeSpan]"0:0:1")InputObject SideIndicator----------- -------------00:00:01 =>0:0:1 <=In the second case, the TimeSpan is converted to a string so the object are different.
Parameters
-CaseSensitive
Indicates that comparisons should be case-sensitive.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-Culture
Specifies the culture to use for comparisons.
| Type: | String |
| Position: | Named |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-DifferenceObject
Specifies the objects that are compared to the reference objects.
| Type: | PSObject[] |
| Position: | 1 |
| Default value: | None |
| Accept pipeline input: | True |
| Accept wildcard characters: | False |
-ExcludeDifferent
Indicates that this cmdlet displays only the characteristics of compared objects that are equal. Thedifferences between the objects are discarded.
Use ExcludeDifferent with IncludeEqual to display only the lines that match between thereference and difference objects.
If ExcludeDifferent is specified without IncludeEqual, there's no output.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-IncludeEqual
IncludeEqual displays the matches between the reference and difference objects.
By default, the output also includes the differences between the reference and differenceobjects.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-PassThru
When you use the PassThru parameter, Compare-Object omits the PSCustomObject wrapperaround the compared objects and returns the differing objects, unchanged.
| Type: | SwitchParameter |
| Position: | Named |
| Default value: | False |
| Accept pipeline input: | False |
| Accept wildcard characters: | 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 propertycan be a script block or a hash table. Valid key-value pairs are:
- Expression -
<string>or<script block>
For more information, seeabout_Calculated_Properties.
| Type: | Object[] |
| Position: | Named |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-ReferenceObject
Specifies an array of objects used as a reference for comparison.
| Type: | PSObject[] |
| Position: | 0 |
| Default value: | None |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
-SyncWindow
Specifies the number of adjacent objects that Compare-Object inspects while looking for a match ina collection of objects. Compare-Object examines adjacent objects when it doesn't find the objectin the same position in a collection. The default value is [Int32]::MaxValue, which means thatCompare-Object examines the entire object collection.
When working with large collections, the default value might not be efficient but is accurate.Specifying a smaller value for SyncWindow can increase performance but could have loweraccuracy.
| Type: | Int32 |
| Position: | Named |
| Default value: | [Int32]::MaxValue |
| Accept pipeline input: | False |
| Accept wildcard characters: | False |
Inputs
PSObject
You can send an object down the pipeline to the DifferenceObject parameter.
Outputs
None
By default, this cmdlet returns no output when the ReferenceObject and the DifferenceObjectare the same.
PSCustomObject
When the objects are different, this cmdlet wraps the differing objects in a PSCustomObjectwrapper with a SideIndicator property to reference the differences.
When you use the IncludeEqual parameter and the objects are the same, the cmdlet returns theobjects wrapped in a PSCustomObject with the SideIndicator property set to ==.
When you use the PassThru parameter, the Type of the object is not changed but the instanceof the object returned has an added NoteProperty named SideIndicator. SideIndicatorshows which input object the output belongs to.
Notes
PowerShell includes the following aliases for Compare-Object:
- Windows:
comparediff
When using the PassThru parameter, the output displayed in the console may not include theSideIndicator property. The default format view for the object type output by Compare-Objectdoes not include the SideIndicator property. For more information see Example 3 in thisarticle.
- about_Calculated_Properties
- ForEach-Object
- Group-Object
- Measure-Object
- New-Object
- Select-Object
- Sort-Object
- Tee-Object
- Where-Object
- Get-Process