issue 4543 (#4799)

Author: davidsmatlak

reference/3.0/Microsoft.PowerShell.Utility/Compare-Object.md

@@ -1,81 +1,144 @@
 ---
-ms.date:  06/09/2017
+ms.date:  09/17/2019
 schema:  2.0.0
 locale:  en-us
 keywords:  powershell,cmdlet
 online version: https://go.microsoft.com/fwlink/?linkid=113286
 external help file:  Microsoft.PowerShell.Commands.Utility.dll-Help.xml
 title:  Compare-Object
 ---
+
 # Compare-Object
 
 ## SYNOPSIS
-
 Compares two sets of objects.
 
 ## SYNTAX
 
+### All
+
 ```
-Compare-Object [-ReferenceObject] <PSObject[]> [-DifferenceObject] <PSObject[]> [-SyncWindow <Int32>]
- [-Property <Object[]>] [-ExcludeDifferent] [-IncludeEqual] [-PassThru] [-Culture <String>] [-CaseSensitive]
- [<CommonParameters>]
+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 set," and the other set is the "difference set."
+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**.
 
-The result of the comparison indicates whether a property value appeared only in the object from the reference set (indicated by the \<= symbol), only in the object from the difference set (indicated by the `=>` symbol) or, if the `IncludeEqual` parameter is specified, in both objects (indicated by the `==` symbol).
+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 set or the difference set is null ($null), this cmdlet generates a terminating error.
+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](../Microsoft.PowerShell.Core/About/about_Splatting.md). And, the examples use two
+text files, with each value on a separate line. `Textfile1.txt` contains the values: dog, squirrel,
+and bird. `Textfile1.txt` contains the values: cat, bird, and racoon.
 
 ## EXAMPLES
 
 ### Example 1: Compare the content of two text files
 
+This example compares the contents of two text files. The output displays only the lines that are
+different between the files. `Textfile1.txt` is the **reference** object (`<=`) and
+`Textfile2.txt`is the **difference** object (`=>`).
+
+Lines with content that appear in both files aren't displayed.
+
 ```powershell
-Compare-Object -ReferenceObject $(Get-Content C:\test\testfile1.txt) -DifferenceObject $(Get-Content C:\test\testfile2.txt)
+Compare-Object -ReferenceObject $(Get-Content -Path C:\Test\Testfile1.txt) -DifferenceObject $(Get-Content -Path C:\Test\Testfile2.txt)
 ```
 
-This command compares the contents of two text files.
-It displays only the lines that appear in one file or in the other file, not lines that appear in both files.
+```Output
+InputObject SideIndicator
+----------- -------------
+cat         =>
+racoon      =>
+dog         <=
+squirrel    <=
+```
 
 ### Example 2: Compare each line of content in two text files
 
+This example uses the **IncludeEqual** to compare each line of content in two text files. All the
+lines of content from both files are displayed.
+
+The **SideIndicator** specifies if the line appears in the `Textfile1.txt` **reference** object
+(`<=`), `Textfile2.txt` **difference** object (`=>`), or both files (`==`).
+
+```powershell
+$objects = @{
+ReferenceObject = $(Get-Content -Path C:\Test\Testfile1.txt)
+DifferenceObject = $(Get-Content -Path C:\Test\Testfile2.txt)
+}
+Compare-Object @objects -IncludeEqual
+```
+
+```Output
+InputObject SideIndicator
+----------- -------------
+bird        ==
+cat         =>
+racoon      =>
+dog         <=
+squirrel    <=
+```
+
+### Example 3: Compare each line of content and exclude the differences
+
+This example uses the **IncludeEqual** and **ExcludeDifferent** parameters to compare each line of
+content in two text files.
+
+Because the command uses the **ExcludeDifferent** parameter, the output only contains lines
+contained in both files, as shown by the **SideIndicator** (`==`).
+
 ```powershell
-Compare-Object -ReferenceObject $(Get-Content C:\Test\testfile1.txt) -DifferenceObject $(Get-Content C:\Test\testfile2.txt) -IncludeEqual
+$objects = @{
+ReferenceObject = $(Get-Content -Path C:\Test\Testfile1.txt)
+DifferenceObject = $(Get-Content -Path C:\Test\Testfile2.txt)
+}
+Compare-Object @objects -IncludeEqual -ExcludeDifferent
+```
+
+```Output
+InputObject SideIndicator
+----------- -------------
+bird        ==
 ```
 
-This command compares each line of content in two text files.
-It displays all lines of content from both files, indicating whether each line appears in only Textfile1.txt or Textfile2.txt or whether each line appears in both files.
+### Example 4: Compare two sets of process objects
 
-### Example 3: Compare two sets of process objects
+This example compares two sets of objects that contain the computer's running processes.
 
 ```powershell
 $Processes_Before = Get-Process
-notepad
+notepad.exe
 $Processes_After = Get-Process
 Compare-Object -ReferenceObject $Processes_Before -DifferenceObject $Processes_After
 ```
 
-```output
-InputObject                          SideIndicator
------------                          -------------
-System.Diagnostics.Process (notepad) =>
+```Output
+InputObject                            SideIndicator
+-----------                            -------------
+System.Diagnostics.Process (notepad)   =>
 ```
 
-These commands compare two sets of process objects.
-
-The first command uses the `Get-Process` cmdlet to get the processes on the computer.
-It stores them in the `$processes_before` variable.
+The `Get-Process` cmdlet gets the computer's running processes and stores them in the
+`$Processes_Before` variable.
 
-The second command starts Notepad.
+The **notepad.exe** application is started.
 
-The third command uses the `Get-Process` cmdlet again and stores the resulting processes in the `$processes_after` variable.
+`Get-Process` gets the computer's updated list of running processes and stores them in the
+`$Processes_After` variable.
 
-The fourth command uses the `Compare-Object` cmdlet to compare the two sets of process objects.
-It displays the differences between them, which include the new instance of Notepad.
+The `Compare-Object` compare the two sets of process objects stored in the `$Processes_Before` and
+`$Processes_After` variables. The output displays the difference, **notepad.exe**, from the
+`$Processes_After` object.
 
 ## PARAMETERS
 
@@ -113,23 +176,29 @@ Accept wildcard characters: False
 
 ### -DifferenceObject
 
-Specifies the objects that are compared to the reference objects.
+Specifies the objects that are compared to the **reference** objects.
 
 ```yaml
 Type: PSObject[]
 Parameter Sets: (All)
 Aliases:
 
 Required: True
-Position: 2
+Position: 1
 Default value: None
 Accept pipeline input: True (ByValue)
 Accept wildcard characters: False
 ```
 
 ### -ExcludeDifferent
 
-Indicates that this cmdlet displays only the characteristics of compared objects that are equal.
+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.
 
 ```yaml
 Type: SwitchParameter
@@ -145,8 +214,10 @@ Accept wildcard characters: False
 
 ### -IncludeEqual
 
-Indicates that this cmdlet displays characteristics of compared objects that are equal.
-By default, only characteristics that differ between the reference and difference objects are displayed.
+**IncludeEqual** displays the matches between the **reference** and **difference** objects.
+
+By default, the output also includes the differences between the **reference** and **difference**
+objects.
 
 ```yaml
 Type: SwitchParameter
@@ -162,7 +233,8 @@ Accept wildcard characters: False
 
 ### -PassThru
 
-When you use the **PassThru** parameter, `Compare-Object` omits the `PSCustomObject` wrapper around the compared objects and returns the differing objects, unchanged.
+When you use the **PassThru** parameter, `Compare-Object` omits the **PSCustomObject** wrapper
+around the compared objects and returns the differing objects, unchanged.
 
 ```yaml
 Type: SwitchParameter
@@ -178,7 +250,7 @@ Accept wildcard characters: False
 
 ### -Property
 
-Specifies an array of properties of the reference and difference objects to compare.
+Specifies an array of properties of the **reference** and **difference** objects to compare.
 
 ```yaml
 Type: Object[]
@@ -210,9 +282,10 @@ Accept wildcard characters: False
 
 ### -SyncWindow
 
-Specifies the number of adjacent objects that this cmdlet inspects while looking for a match in a collection of objects.
-This cmdlet examines adjacent objects when it does not find the object in the same position in a collection.
-The default value is `[Int32]::MaxValue`, which means that this cmdlet examines the entire object collection.
+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.
 
 ```yaml
 Type: Int32
@@ -228,23 +301,28 @@ Accept wildcard characters: False
 
 ### CommonParameters
 
-This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
+This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable,
+-InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose,
+-WarningAction, and -WarningVariable. For more information, see [about_CommonParameters](https://go.microsoft.com/fwlink/?LinkID=113216).
 
 ## INPUTS
 
 ### System.Management.Automation.PSObject
 
-You can pipe a **DifferenceObject** object to this cmdlet.
+You can send an object down the pipeline to the **DifferenceObject** parameter.
 
 ## OUTPUTS
 
 ### None
 
-If the objects are the same, nothing is returned.
+If the **reference** object and the **difference** object are the same, there's no output.
 
 ### System.Management.Automation.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, `Compare-Object` omits the `PSCustomObject` wrapper around the compared objects and returns the differing objects, unchanged.
+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, `Compare-Object` omits the `PSCustomObject` wrapper around the compared
+objects and returns the differing objects, unchanged.
 
 ## NOTES
 
@@ -267,4 +345,3 @@ If the objects are different, `Compare-Object` wraps the differing objects in a
 [Where-Object](../Microsoft.PowerShell.Core/Where-Object.md)
 
 [Get-Process](../Microsoft.PowerShell.Management/Get-Process.md)
-