Skip to content

Commit

Permalink
(GH-143023) Clarify Width param for Out-File (#10310)
Browse files Browse the repository at this point in the history 
Prior to this change, the **Width** paramter of the `Out-File` cmdlet
stated that it specified the number of characters in each line of
output rather than the maximum number of characters.

This change:

- Clarifies the parameter documentation for specifying the maximum
  width, rather than the total width.
- Resolves #10309
- Fixes AB#132023
  • Loading branch information
@michaeltlombardi
michaeltlombardi committed Jul 27, 2023
1 parent 6200d65 commit ec789da
Show file tree
Hide file tree
Showing 4 changed files with 117 additions and 105 deletions.
57 changes: 30 additions & 27 deletions reference/5.1/Microsoft.PowerShell.Utility/Out-File.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Utility
ms.date: 12/12/2022
ms.date: 07/27/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/out-file?view=powershell-5.1&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Out-File
Expand All @@ -18,15 +18,15 @@ Sends output to a file.
### ByPath (Default)

```
Out-File [-FilePath] <string> [[-Encoding] <string>] [-Append] [-Force] [-NoClobber] [-Width <int>]
[-NoNewline] [-InputObject <psobject>] [-WhatIf] [-Confirm] [<CommonParameters>]
Out-File [-FilePath] <string> [[-Encoding] <string>] [-Append] [-Force] [-NoClobber]
[-Width <int>] [-NoNewline] [-InputObject <psobject>] [-WhatIf] [-Confirm] [<CommonParameters>]
```

### ByLiteralPath

```
Out-File [[-Encoding] <string>] -LiteralPath <string> [-Append] [-Force] [-NoClobber] [-Width <int>]
[-NoNewline] [-InputObject <psobject>] [-WhatIf] [-Confirm] [<CommonParameters>]
Out-File [[-Encoding] <string>] -LiteralPath <string> [-Append] [-Force] [-NoClobber]
[-Width <int>] [-NoNewline] [-InputObject <psobject>] [-WhatIf] [-Confirm] [<CommonParameters>]
```

## DESCRIPTION
Expand Down Expand Up @@ -95,15 +95,15 @@ Out-File -FilePath .\Process.txt -InputObject $Procs -Encoding ASCII -Width 50
```

The `Get-Process` cmdlet gets the list of processes running on the local computer. The **Process**
objects are stored in the variable, `$Procs`. `Out-File` uses the **FilePath** parameter and creates
a file in the current directory named **Process.txt**. The **InputObject** parameter passes the
process objects in `$Procs` to the file **Process.txt**. The **Encoding** parameter converts the
output to **ASCII** format. The **Width** parameter limits each line in the file to 50 characters so
some data might be truncated.
objects are stored in the variable, `$Procs`. `Out-File` uses the **FilePath** parameter and
creates a file in the current directory named **Process.txt**. The **InputObject** parameter passes
the process objects in `$Procs` to the file **Process.txt**. The **Encoding** parameter converts
the output to **ASCII** format. The **Width** parameter limits each line in the file to 50
characters so some data might be truncated.

### Example 4: Use a provider and send output to a file

This example shows how to use the `Out-File` cmdlet when you are not in a **FileSystem** provider
This example shows how to use the `Out-File` cmdlet when you aren't in a **FileSystem** provider
drive. Use the `Get-PSProvider` cmdlet to view the providers on your local computer. For more
information, see [about_Providers](../Microsoft.Powershell.Core/About/about_Providers.md).

Expand Down Expand Up @@ -132,8 +132,8 @@ The `Set-Location` command uses the **Path** parameter to set the current locati
provider `Alias:`. The `Get-Location` cmdlet displays the complete path for `Alias:`.
`Get-ChildItem` sends objects down the pipeline to the `Out-File` cmdlet. `Out-File` uses the
**FilePath** parameter to specify the complete path and filename for the output,
**C:\TestDir\AliasNames.txt**. The `Get-Content` cmdlet uses the **Path** parameter and displays the
file's content in the PowerShell console.
**C:\TestDir\AliasNames.txt**. The `Get-Content` cmdlet uses the **Path** parameter and displays
the file's content in the PowerShell console.

### Example 5: Set file output width for entire scope

Expand All @@ -151,7 +151,9 @@ function DemoDefaultOutFileWidth() {
Get-ChildItem Env:\ > $logFile
Get-Service -ErrorAction Ignore | Format-Table -AutoSize | Out-File $logFile -Append
Get-Service -ErrorAction Ignore |
Format-Table -AutoSize |
Out-File $logFile -Append
Get-Process | Format-Table Id,SI,Name,Path,MainWindowTitle >> $logFile
}
Expand Down Expand Up @@ -234,8 +236,8 @@ Accept wildcard characters: False

### -Force

Overrides the read-only attribute and overwrites an existing read-only file. The **Force** parameter
does not override security restrictions.
Overrides the read-only attribute and overwrites an existing read-only file. The **Force**
parameter doesn't override security restrictions.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand Down Expand Up @@ -268,10 +270,11 @@ Accept wildcard characters: False

### -LiteralPath

Specifies the path to the output file. The **LiteralPath** parameter is used exactly as it is typed.
Wildcard characters are not accepted. If the path includes escape characters, enclose it in single
Specifies the path to the output file. The **LiteralPath** parameter is used exactly as it's typed.
Wildcard characters aren't accepted. If the path includes escape characters, enclose it in single
quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape
sequences. For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
sequences. For more information, see
[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).

```yaml
Type: System.String
Expand Down Expand Up @@ -305,7 +308,7 @@ Accept wildcard characters: False

### -NoNewline

Specifies that the content written to the file does not end with a newline character. The string
Specifies that the content written to the file doesn't end with a newline character. The string
representations of the input objects are concatenated to form the output. No spaces or newlines are
inserted between the output strings. No newline is added after the last output string.

Expand All @@ -323,11 +326,11 @@ Accept wildcard characters: False

### -Width

Specifies the number of characters in each line of output. Any additional characters are truncated,
not wrapped. If this parameter is not used, the width is determined by the characteristics of the
host. The default for the PowerShell console is 80 characters. If you want to control the width for
all invocations of `Out-File` as well as the redirection operators (`>` and `>>`), set
`$PSDefaultParameterValues['out-file:width'] = 2000` before using `Out-File`.
Specifies the maximum number of characters in each line of output. Any additional characters are
truncated, not wrapped. If this parameter isn't used, the width is determined by the
characteristics of the host. The default for the PowerShell console is 80 characters. If you want
to control the width for all invocations of `Out-File` as well as the redirection operators (`>`
and `>>`), set `$PSDefaultParameterValues['out-file:width'] = 2000` before using `Out-File`.

```yaml
Type: System.Int32
Expand Down Expand Up @@ -359,7 +362,7 @@ Accept wildcard characters: False

### -WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.
Shows what would happen if the cmdlet runs. The cmdlet isn't run.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand Down Expand Up @@ -402,7 +405,7 @@ To send a PowerShell command's output to the `Out-File` cmdlet, use the pipeline
can store data in a variable and use the **InputObject** parameter to pass data to the `Out-File`
cmdlet.

`Out-File` saves data to a file but it does not produce any output objects to the pipeline.
`Out-File` saves data to a file but it doesn't produce any output objects to the pipeline.

## RELATED LINKS

Expand Down
55 changes: 29 additions & 26 deletions reference/7.2/Microsoft.PowerShell.Utility/Out-File.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
external help file: Microsoft.PowerShell.Commands.Utility.dll-Help.xml
Locale: en-US
Module Name: Microsoft.PowerShell.Utility
ms.date: 12/12/2022
ms.date: 07/27/2023
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.utility/out-file?view=powershell-7.2&WT.mc_id=ps-gethelp
schema: 2.0.0
title: Out-File
Expand Down Expand Up @@ -95,15 +95,15 @@ Out-File -FilePath .\Process.txt -InputObject $Procs -Encoding ASCII -Width 50
```

The `Get-Process` cmdlet gets the list of processes running on the local computer. The **Process**
objects are stored in the variable, `$Procs`. `Out-File` uses the **FilePath** parameter and creates
a file in the current directory named **Process.txt**. The **InputObject** parameter passes the
process objects in `$Procs` to the file **Process.txt**. The **Encoding** parameter converts the
output to **ASCII** format. The **Width** parameter limits each line in the file to 50 characters so
some data might be truncated.
objects are stored in the variable, `$Procs`. `Out-File` uses the **FilePath** parameter and
creates a file in the current directory named **Process.txt**. The **InputObject** parameter passes
the process objects in `$Procs` to the file **Process.txt**. The **Encoding** parameter converts
the output to **ASCII** format. The **Width** parameter limits each line in the file to 50
characters so some data might be truncated.

### Example 4: Use a provider and send output to a file

This example shows how to use the `Out-File` cmdlet when you are not in a **FileSystem** provider
This example shows how to use the `Out-File` cmdlet when you aren't in a **FileSystem** provider
drive. Use the `Get-PSProvider` cmdlet to view the providers on your local computer. For more
information, see [about_Providers](../Microsoft.Powershell.Core/About/about_Providers.md).

Expand Down Expand Up @@ -132,8 +132,8 @@ The `Set-Location` command uses the **Path** parameter to set the current locati
provider `Alias:`. The `Get-Location` cmdlet displays the complete path for `Alias:`.
`Get-ChildItem` sends objects down the pipeline to the `Out-File` cmdlet. `Out-File` uses the
**FilePath** parameter to specify the complete path and filename for the output,
**C:\TestDir\AliasNames.txt**. The `Get-Content` cmdlet uses the **Path** parameter and displays the
file's content in the PowerShell console.
**C:\TestDir\AliasNames.txt**. The `Get-Content` cmdlet uses the **Path** parameter and displays
the file's content in the PowerShell console.

### Example 5: Set file output width for entire scope

Expand All @@ -151,7 +151,9 @@ function DemoDefaultOutFileWidth() {
Get-ChildItem Env:\ > $logFile
Get-Service -ErrorAction Ignore | Format-Table -AutoSize | Out-File $logFile -Append
Get-Service -ErrorAction Ignore |
Format-Table -AutoSize |
Out-File $logFile -Append
Get-Process | Format-Table Id,SI,Name,Path,MainWindowTitle >> $logFile
}
Expand Down Expand Up @@ -201,8 +203,8 @@ The acceptable values for this parameter are as follows:
- `utf8NoBOM`: Encodes in UTF-8 format without Byte Order Mark (BOM)
- `utf32`: Encodes in UTF-32 format.

Beginning with PowerShell 6.2, the **Encoding** parameter also allows numeric IDs of registered code
pages (like `-Encoding 1251`) or string names of registered code pages (like
Beginning with PowerShell 6.2, the **Encoding** parameter also allows numeric IDs of registered
code pages (like `-Encoding 1251`) or string names of registered code pages (like
`-Encoding "windows-1251"`). For more information, see the .NET documentation for
[Encoding.CodePage](/dotnet/api/system.text.encoding.codepage?view=netcore-2.2).

Expand Down Expand Up @@ -241,8 +243,8 @@ Accept wildcard characters: False

### -Force

Overrides the read-only attribute and overwrites an existing read-only file. The **Force** parameter
does not override security restrictions.
Overrides the read-only attribute and overwrites an existing read-only file. The **Force**
parameter doesn't override security restrictions.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand Down Expand Up @@ -275,10 +277,11 @@ Accept wildcard characters: False

### -LiteralPath

Specifies the path to the output file. The **LiteralPath** parameter is used exactly as it is typed.
Wildcard characters are not accepted. If the path includes escape characters, enclose it in single
Specifies the path to the output file. The **LiteralPath** parameter is used exactly as it's typed.
Wildcard characters aren't accepted. If the path includes escape characters, enclose it in single
quotation marks. Single quotation marks tell PowerShell not to interpret any characters as escape
sequences. For more information, see [about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).
sequences. For more information, see
[about_Quoting_Rules](../Microsoft.Powershell.Core/About/about_Quoting_Rules.md).

```yaml
Type: System.String
Expand Down Expand Up @@ -312,7 +315,7 @@ Accept wildcard characters: False

### -NoNewline

Specifies that the content written to the file does not end with a newline character. The string
Specifies that the content written to the file doesn't end with a newline character. The string
representations of the input objects are concatenated to form the output. No spaces or newlines are
inserted between the output strings. No newline is added after the last output string.

Expand All @@ -330,11 +333,11 @@ Accept wildcard characters: False

### -Width

Specifies the number of characters in each line of output. Any additional characters are truncated,
not wrapped. If this parameter is not used, the width is determined by the characteristics of the
host. The default for the PowerShell console is 80 characters. If you want to control the width for
all invocations of `Out-File` as well as the redirection operators (`>` and `>>`), set
`$PSDefaultParameterValues['out-file:width'] = 2000` before using `Out-File`.
Specifies the maximum number of characters in each line of output. Any additional characters are
truncated, not wrapped. If this parameter isn't used, the width is determined by the
characteristics of the host. The default for the PowerShell console is 80 characters. If you want
to control the width for all invocations of `Out-File` as well as the redirection operators (`>`
and `>>`), set `$PSDefaultParameterValues['out-file:width'] = 2000` before using `Out-File`.

```yaml
Type: System.Int32
Expand Down Expand Up @@ -366,7 +369,7 @@ Accept wildcard characters: False

### -WhatIf

Shows what would happen if the cmdlet runs. The cmdlet is not run.
Shows what would happen if the cmdlet runs. The cmdlet isn't run.

```yaml
Type: System.Management.Automation.SwitchParameter
Expand Down Expand Up @@ -409,10 +412,10 @@ To send a PowerShell command's output to the `Out-File` cmdlet, use the pipeline
can store data in a variable and use the **InputObject** parameter to pass data to the `Out-File`
cmdlet.

`Out-File` saves data to a file but it does not produce any output objects to the pipeline.
`Out-File` saves data to a file but it doesn't produce any output objects to the pipeline.

PowerShell 7.2 added the ability to control how ANSI escape sequences are rendered. ANSI-decorated
output that is passed to `Out-File` can be altered based on the setting of the
output that's passed to `Out-File` can be changed based on the setting of the
`$PSStyle.OutputRendering` property. For more information, see
[about_ANSI_Terminals](/powershell/module/microsoft.powershell.core/about/about_ansi_terminals).

Expand Down
Loading

0 comments on commit ec789da

Please sign in to comment.