From 3499355ed4f8d672f572b484d48460046e994e2b Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 12:26:45 -0600 Subject: [PATCH 1/2] Document PATHEXT environment var behavior in PS --- .../About/about_Command_Precedence.md | 63 ++++++++++++------ .../About/about_Environment_Variables.md | 26 +++++++- .../About/about_Command_Precedence.md | 63 ++++++++++++------ .../About/about_Environment_Variables.md | 59 +++++++++++++++-- .../About/about_Command_Precedence.md | 64 +++++++++++++------ .../About/about_Environment_Variables.md | 59 +++++++++++++++-- .../About/about_Command_Precedence.md | 64 +++++++++++++------ .../About/about_Environment_Variables.md | 40 ++++++++++-- 8 files changed, 334 insertions(+), 104 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index cc6750bdeef2..e0c9830c73d1 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index fe27289948be..3c2e8617b509 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-5.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -323,6 +323,30 @@ The environment variables that store preferences include: For more information, see [about_PSModulePath](about_PSModulePath.md). +## Other environment variables used by PowerShell + +### Path information + +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension the the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. For more + information, see the documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + ## See also - [Environment (provider)](../About/about_Environment_Provider.md) diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index cd709f977aad..8ec55977ed64 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index c16f52d12a93..2822d7f87717 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -359,14 +359,59 @@ The environment variables that store preferences include: For more information, see [about_Telemetry](about_Telemetry.md). -## Third-party environment variables +## Other environment variables used by PowerShell -On non-Windows platforms, PowerShell uses the following XDG environment -variables as defined by the [XDG Base Directory Specification][xdg-bds]. +### Path information -- **XDG_CONFIG_HOME** -- **XDG_DATA_HOME** -- **XDG_CACHE_HOME** +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension the the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. For more + information, see the documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + +- XDG variables + + On non-Windows platforms, PowerShell uses the following XDG environment + variables as defined by the [XDG Base Directory Specification][xdg-bds]. + + - **XDG_CONFIG_HOME** + - **XDG_DATA_HOME** + - **XDG_CACHE_HOME** + +### Terminal features + +Beginning in PowerShell 7.2, the following environment variables can be used to +control the Virtual Terminal features like ANSI escape sequences that colorize +output. Support for ANSI escape sequences can be turned off using the **TERM** +or **NO_COLOR** environment variables. + +- **TERM** + + The following values of `$env:TERM` change the behavior as follows: + + - `dumb` - sets `$Host.UI.SupportsVirtualTerminal = $false` + - `xterm-mono` - sets `$PSStyle.OutputRendering = PlainText` + - `xtermm` - sets `$PSStyle.OutputRendering = PlainText` + +- **NO_COLOR** + + If `$env:NO_COLOR` exists, then `$PSStyle.OutputRendering` is set to + **PlainText**. For more information about the **NO_COLOR** environment + variable, see [https://no-color.org/](https://no-color.org/). ## See also diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index 65f2764e8804..b8538706da9b 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also @@ -327,4 +350,3 @@ For more information, see `Import-Module` and `Import-PSSession` below. - [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) - [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module) - [Import-PSSession](xref:Microsoft.PowerShell.Utility.Import-PSSession) - diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 726b503eb88f..b26adcbbb343 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.1&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -359,14 +359,59 @@ The environment variables that store preferences include: For more information, see [about_Telemetry](about_Telemetry.md). -## Third-party environment variables +## Other environment variables used by PowerShell -On non-Windows platforms, PowerShell uses the following XDG environment -variables as defined by the [XDG Base Directory Specification][xdg-bds]. +### Path information -- **XDG_CONFIG_HOME** -- **XDG_DATA_HOME** -- **XDG_CACHE_HOME** +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension the the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. For more + information, see the documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + +- XDG variables + + On non-Windows platforms, PowerShell uses the following XDG environment + variables as defined by the [XDG Base Directory Specification][xdg-bds]. + + - **XDG_CONFIG_HOME** + - **XDG_DATA_HOME** + - **XDG_CACHE_HOME** + +### Terminal features + +Beginning in PowerShell 7.2, the following environment variables can be used to +control the Virtual Terminal features like ANSI escape sequences that colorize +output. Support for ANSI escape sequences can be turned off using the **TERM** +or **NO_COLOR** environment variables. + +- **TERM** + + The following values of `$env:TERM` change the behavior as follows: + + - `dumb` - sets `$Host.UI.SupportsVirtualTerminal = $false` + - `xterm-mono` - sets `$PSStyle.OutputRendering = PlainText` + - `xtermm` - sets `$PSStyle.OutputRendering = PlainText` + +- **NO_COLOR** + + If `$env:NO_COLOR` exists, then `$PSStyle.OutputRendering` is set to + **PlainText**. For more information about the **NO_COLOR** environment + variable, see [https://no-color.org/](https://no-color.org/). ## See also diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md index b2701fa63a50..8d299dca9f9e 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Command_Precedence.md @@ -1,7 +1,7 @@ --- description: Describes how PowerShell determines which command to run. Locale: en-US -ms.date: 02/13/2020 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_command_precedence?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Command Precedence @@ -98,7 +98,8 @@ C:\temp\test\[a1].ps1 You can see from the output that `[a1].ps1` runs this time because the literal match is the only file match for that wildcard pattern. -For more information about how PowerShell uses wildcards, see [about_Wildcards](about_Wildcards.md). +For more information about how PowerShell uses wildcards, see +[about_Wildcards](about_Wildcards.md). > [!NOTE] > To limit the search to a relative path, you must prefix the script name with @@ -109,10 +110,10 @@ For more information about how PowerShell uses wildcards, see [about_Wildcards]( If you do not specify a path, PowerShell uses the following precedence order when it runs commands for all items loaded in the current session: - 1. Alias - 2. Function - 3. Cmdlet - 4. External executable files (programs and non-PowerShell scripts) +1. Alias +2. Function +3. Cmdlet +4. External executable files (programs and non-PowerShell scripts) Therefore, if you type "help", PowerShell first looks for an alias named `help`, then a function named `Help`, and finally a cmdlet named `Help`. It @@ -159,12 +160,13 @@ Also, if you type a function at the command line and then import a function with the same name, the original function is replaced and is no longer accessible. -### Finding hidden commands +## Finding hidden commands -The **All** parameter of the [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) -cmdlet gets all commands with the specified name, even if they are hidden -or replaced. Beginning in PowerShell 3.0, by default, `Get-Command` -gets only the commands that run when you type the command name. +The **All** parameter of the +[Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) cmdlet gets all +commands with the specified name, even if they are hidden or replaced. +Beginning in PowerShell 3.0, by default, `Get-Command` gets only the commands +that run when you type the command name. In the following examples, the session includes a `Get-Date` function and a [Get-Date](xref:Microsoft.PowerShell.Utility.Get-Date) cmdlet. @@ -203,7 +205,7 @@ the command from other commands that might have the same name. You can use this method to run any command, but it is especially useful for running hidden commands. -#### Qualified names +### Using qualified names Using the module-qualified name of a cmdlet allows you to run commands hidden by an item with the same name. For example, you can run the `Get-Date` cmdlet @@ -249,14 +251,16 @@ Microsoft.PowerShell.Utility > [!NOTE] > You cannot qualify variables or aliases. -#### Call operator +### Using the call operator -You can also use the `Call` operator `&` to run hidden commands by combining -it with a call to [Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) -(the alias is "dir"), `Get-Command` or +You can also use the `Call` operator `&` to run hidden commands by combining it +with a call to +[Get-ChildItem](xref:Microsoft.PowerShell.Management.Get-ChildItem) (the alias +is "dir"), `Get-Command` or [Get-Module](xref:Microsoft.PowerShell.Core.Get-Module). -The call operator executes strings and script blocks in a child scope. For more information, see [about_Operators](about_Operators.md). +The call operator executes strings and script blocks in a child scope. For more +information, see [about_Operators](about_Operators.md). For example, if you have a function named `Map` that is hidden by an alias named `Map`, use the following command to run the function. @@ -281,7 +285,7 @@ $myMap = (Get-Command -Name map -CommandType function) &($myMap) ``` -### Replaced items +## Replaced items A "replaced" item is one that you can no longer access. You can replace items by importing items of the same name from a module or snap-in. @@ -294,7 +298,7 @@ Variables and aliases cannot be hidden because you cannot use a call operator or a qualified name to run them. When you import variables and aliases from a module or snap-in, they replace variables in the session with the same name. -### Avoiding name conflicts +## Avoiding name conflicts The best way to manage command name conflicts is to prevent them. When you name your commands, use a unique name. For example, add your initials or company @@ -315,7 +319,26 @@ and `Set-Date` cmdlets that come with PowerShell when you import the Import-Module -Name DateFunctions -Prefix ZZ ``` -For more information, see `Import-Module` and `Import-PSSession` below. +## Running external executables + +PowerShell treats the file extensions listed in the `$env:PATHEXT` environment +variable as executable files. Windows executable files are files with `.COM`, +`.CPL`, or `.EXE` file extensions. Windows executables and any other files with +extensions listed in `$env:PATHEXT` are executed in the current console +session. + +Files that are not Windows executables are handed to Windows to process. Windows +looks up the file association and executes the default Windows Shell verb for +the extension. For Windows to support the execution by file extension, the +association must be registered with the system. + +You can register the executable engine for a file extension using the `ftype` +and `assoc` commands of the CMD command shell. PowerShell has no direct method +to register the file handler. For more information, see the documentation for +the [ftype](/windows-server/administration/windows-commands/ftype) command. + +For PowerShell to see a file extension as executable in the current session, +you must add the extension to the `$env:PATHEXT` environment variable. ## See also @@ -327,4 +350,3 @@ For more information, see `Import-Module` and `Import-PSSession` below. - [Get-Command](xref:Microsoft.PowerShell.Core.Get-Command) - [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module) - [Import-PSSession](xref:Microsoft.PowerShell.Utility.Import-PSSession) - diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index ac0f912654cb..5ce8bb449b53 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -1,7 +1,7 @@ --- description: Describes how to access Windows environment variables in PowerShell. Locale: en-US -ms.date: 08/18/2021 +ms.date: 11/15/2021 online version: https://docs.microsoft.com/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7.2&WT.mc_id=ps-gethelp schema: 2.0.0 title: about Environment Variables @@ -365,14 +365,40 @@ The environment variables that store preferences include: installer packages to record the method and source of installation for PowerShell. -## Third-party environment variables +## Other environment variables used by PowerShell -On non-Windows platforms, PowerShell uses the following XDG environment -variables as defined by the [XDG Base Directory Specification][xdg-bds]. +### Path information -- **XDG_CONFIG_HOME** -- **XDG_DATA_HOME** -- **XDG_CACHE_HOME** +- **PATHEXT** + + The `$env:PATHEXT` variable contains a list of file extensions that Windows + considers to be executable files. When a script file with one of the listed + extensions is executed from PowerShell, the script runs in the current + console or terminal session. If the file extension is not listed, the script + runs in a new console session. + + To ensure that scripts for another scripting language run in the current + console session, add the file extension used by the scripting language. For + example, to run Python scripts in the current console, add the `.py` + extension the the environment variable. For Windows to support the `.py` + extension as an executable file you must register the file extension using + the `ftype` and `assoc` commands of the CMD command shell. For more + information, see the documentation for the + [ftype](/windows-server/administration/windows-commands/ftype) command. + + PowerShell scripts always start in the current console session. You do not + need to add the `.PS1` extension. + +- XDG variables + + On non-Windows platforms, PowerShell uses the following XDG environment + variables as defined by the [XDG Base Directory Specification][xdg-bds]. + + - **XDG_CONFIG_HOME** + - **XDG_DATA_HOME** + - **XDG_CACHE_HOME** + +### Terminal features Beginning in PowerShell 7.2, the following environment variables can be used to control the Virtual Terminal features like ANSI escape sequences that colorize From 9b1c601d9d10bd7d581c528c393dcf4d380d897a Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Mon, 15 Nov 2021 13:27:18 -0600 Subject: [PATCH 2/2] fix typo --- .../About/about_Environment_Variables.md | 7 ++++--- .../About/about_Environment_Variables.md | 9 +++++---- .../About/about_Environment_Variables.md | 9 +++++---- .../About/about_Environment_Variables.md | 9 +++++---- 4 files changed, 19 insertions(+), 15 deletions(-) diff --git a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 3c2e8617b509..17e332e47744 100644 --- a/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/5.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -338,10 +338,11 @@ The environment variables that store preferences include: To ensure that scripts for another scripting language run in the current console session, add the file extension used by the scripting language. For example, to run Python scripts in the current console, add the `.py` - extension the the environment variable. For Windows to support the `.py` + extension to the environment variable. For Windows to support the `.py` extension as an executable file you must register the file extension using - the `ftype` and `assoc` commands of the CMD command shell. For more - information, see the documentation for the + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the [ftype](/windows-server/administration/windows-commands/ftype) command. PowerShell scripts always start in the current console session. You do not diff --git a/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 2822d7f87717..80ccf958e865 100644 --- a/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.0/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -274,7 +274,7 @@ The environment variables that store preferences include: hexadecimal suffix so that there is a a unique filename per installation. > [!NOTE] - > If command discovery isn't working correctly, for example Intellisense + > If command discovery isn't working correctly, for example IntelliSense > shows commands that don't exist, you can delete the cache file. The cache > is recreated the next time you start PowerShell. @@ -374,10 +374,11 @@ The environment variables that store preferences include: To ensure that scripts for another scripting language run in the current console session, add the file extension used by the scripting language. For example, to run Python scripts in the current console, add the `.py` - extension the the environment variable. For Windows to support the `.py` + extension to the environment variable. For Windows to support the `.py` extension as an executable file you must register the file extension using - the `ftype` and `assoc` commands of the CMD command shell. For more - information, see the documentation for the + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the [ftype](/windows-server/administration/windows-commands/ftype) command. PowerShell scripts always start in the current console session. You do not diff --git a/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index b26adcbbb343..dc59981986a7 100644 --- a/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.1/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -274,7 +274,7 @@ The environment variables that store preferences include: hexadecimal suffix so that there is a a unique filename per installation. > [!NOTE] - > If command discovery isn't working correctly, for example Intellisense + > If command discovery isn't working correctly, for example IntelliSense > shows commands that don't exist, you can delete the cache file. The cache > is recreated the next time you start PowerShell. @@ -374,10 +374,11 @@ The environment variables that store preferences include: To ensure that scripts for another scripting language run in the current console session, add the file extension used by the scripting language. For example, to run Python scripts in the current console, add the `.py` - extension the the environment variable. For Windows to support the `.py` + extension to the environment variable. For Windows to support the `.py` extension as an executable file you must register the file extension using - the `ftype` and `assoc` commands of the CMD command shell. For more - information, see the documentation for the + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the [ftype](/windows-server/administration/windows-commands/ftype) command. PowerShell scripts always start in the current console session. You do not diff --git a/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md b/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md index 5ce8bb449b53..911ffcc81563 100644 --- a/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md +++ b/reference/7.2/Microsoft.PowerShell.Core/About/about_Environment_Variables.md @@ -274,7 +274,7 @@ The environment variables that store preferences include: hexadecimal suffix so that there is a a unique filename per installation. > [!NOTE] - > If command discovery isn't working correctly, for example Intellisense + > If command discovery isn't working correctly, for example IntelliSense > shows commands that don't exist, you can delete the cache file. The cache > is recreated the next time you start PowerShell. @@ -380,10 +380,11 @@ The environment variables that store preferences include: To ensure that scripts for another scripting language run in the current console session, add the file extension used by the scripting language. For example, to run Python scripts in the current console, add the `.py` - extension the the environment variable. For Windows to support the `.py` + extension to the environment variable. For Windows to support the `.py` extension as an executable file you must register the file extension using - the `ftype` and `assoc` commands of the CMD command shell. For more - information, see the documentation for the + the `ftype` and `assoc` commands of the CMD command shell. PowerShell has no + direct method to register the file handler. For more information, see the + documentation for the [ftype](/windows-server/administration/windows-commands/ftype) command. PowerShell scripts always start in the current console session. You do not