Skip to content

Commit 325fbb1

Browse files
sdwheelerCopilotmichaeltlombardi
authored
Fixes #12624 - Add more specific cases of sensitivity (#12637)
* Add more specific cases of sensitivity * Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com> * Expand example * fix about_Split link * fix xref links --------- Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> Co-authored-by: Mikey Lombardi (He/Him) <michael.t.lombardi@gmail.com> Co-authored-by: Mikey Lombardi <mlombardi@microsoft.com>
1 parent 8da5bfe commit 325fbb1

File tree

4 files changed

+904
-76
lines changed

4 files changed

+904
-76
lines changed

‎reference/5.1/Microsoft.PowerShell.Core/About/about_Case-Sensitivity.md‎

Lines changed: 226 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,7 @@
11
---
22
description: This article explains how PowerShell handles case-sensitivity.
33
Locale: en-US
4-
ms.custom: wiki-migration
5-
ms.date: 06/06/2022
4+
ms.date: 01/06/2026
65
online version: https://learn.microsoft.com/powershell/module/microsoft.powershell.core/about/about_case-sensitivity?view=powershell-5.1&WT.mc_id=ps-gethelp
76
title: about_Case-Sensitivity
87
---
@@ -14,38 +13,246 @@ PowerShell is as case-insensitive as possible while preserving case.
1413

1514
## Long description
1615

17-
As a general principle, PowerShell is as case insensitive as possible while
16+
As a general principle, PowerShell is case-insensitive wherever possible while
1817
preserving case and not breaking the underlying OS.
1918

20-
### On Unix-based systems
19+
Windows-based systems are case-insensitive for most operations. However,
20+
non-Windows systems are case-sensitive for most operations, especially for
21+
file system and environment variable access.
2122

22-
On Unix-based systems, PowerShell is case-sensitive because filesystem
23-
manipulation and environment variables directly affect the underlying
24-
operating system and integration with other tools.
23+
PowerShell is guaranteed to be case-insensitive on all systems for the
24+
following areas:
2525

26-
## On all systems
26+
- Variable names
27+
- Operator names
28+
- Non-dictionary member-access
29+
- Command discovery of PowerShell commands and aliases. This excludes
30+
ExternalScript and Application commands.
31+
- Parameter names and aliases
32+
- PowerShell language keywords
33+
- `using namespace` statements
34+
- Type literals
35+
- `#Requires` statements
36+
- Comment-based help keywords
37+
- PSProvider names
38+
- PSDrive names
39+
- Scope modifiers
2740

28-
- PowerShell variables are case-insensitive
29-
30-
Variable names have no interaction between them and the underlying operating
31-
system. PowerShell treats them case-insensitively.
41+
## Special cases
3242

3343
- Module names are case-insensitive (with exceptions)
3444

3545
The _name_ of the module is purely a PowerShell concept and treated
3646
case-insensitively. However, there is a strong mapping to a foldername, which
37-
can be case-sensitive in the underlying operating system. Importing two|
47+
can be case-sensitive in the underlying operating system. Importing two
3848
modules with the same case-insensitive name has the same behavior as
3949
importing two modules with the same name from different paths.
4050

4151
The name of a module is stored in the session state using the case by which
4252
it was imported. The name, as stored in the session state, is used
43-
`Update-Help` when looking for new help files.
44-
The web service that serves the help files for Microsoft uses a
45-
case-sensitive filesystem. When the case of the imported name of the module
46-
doesn't match, `Update-Help` can't find the help files and reports an error.
53+
by `Update-Help` when looking for new help files. The web service that serves
54+
the help files for Microsoft uses a case-sensitive file system. When the case
55+
of the imported name of the module doesn't match, `Update-Help` can't find
56+
the help files and reports an error.
57+
58+
- [PS providers][05]:
59+
60+
The `FileSystem` and `Environment` providers are case-sensitive on
61+
non-Windows systems. Generally, operations involving paths or environment
62+
variables are case-sensitive on such systems.
63+
64+
However, [wildcard matching][09] by [provider cmdlets][02] is
65+
case-insensitive, irrespective of the system.
66+
67+
```powershell
68+
PS /home/user01> New-Item -Path Temp:foo.txt -Force
69+
70+
Directory: /tmp
71+
72+
UnixMode User Group LastWriteTime Size Name
73+
-------- ---- ----- ------------- ---- ----
74+
-rw-r--r-- user01 user01 1/6/2026 10:53 0 foo.txt
75+
76+
PS /home/user01> (Get-Item -Path Temp:FOO.txt).Name
77+
Get-Item: Cannot find path 'Temp:/FOO.txt' because it does not exist.
78+
79+
PS /home/user01> (Get-Item -Path Temp:F[O]*.txt).Name
80+
foo.txt
81+
82+
PS /home/user01> (Get-Item -Path Env:hOM[E]).Name
83+
HOME
84+
```
85+
86+
- Parameter set names are case-sensitive.
87+
88+
The `DefaultParameterSetName` case must be identical to `ParameterSetName`.
89+
90+
- .NET methods often exhibit case-sensitive behavior by default.
91+
92+
Examples include:
93+
94+
- Equivalent .NET methods (without explicit opt-in) for common PowerShell
95+
operators such as:
96+
- `Array.Contains()`, `String.Contains()`, `String.Replace()`,
97+
`Regex.Match()`, `Regex.Replace()`
98+
- Reflection; member names must use the correct case.
99+
- Non-literal dictionary instantiation. For example:
100+
- `[hashtable]::new()` has case-sensitive keys, whereas a hashtable
101+
literal `@{}` has case-insensitive keys.
102+
- `[ordered]::new()` has case-sensitive keys, whereas a `[ordered] @{}` has
103+
case-insensitive keys. The `[ordered]` type _accelerator_ isn't available
104+
in PowerShell v5.1 and earlier.
105+
- Explicitly calling `Enum.Parse()` is case-sensitive by default, whereas
106+
PowerShell typically handles enums in a case-insensitive manner.
107+
108+
- `-Unique` cmdlets:
109+
- [`Select-Object -Unique`][21] and [`Get-Unique`][15] are case-sensitive by
110+
default. The [`-CaseInsensitive`][20] switch was added in PS v7.4.
111+
- [`Sort-Object -Unique`][25] is case-insensitive by default, but has always
112+
had the [`-CaseSensitive`][24] switch.
113+
114+
- [`Compare-Object`][11] is case-insensitive by default, but has a
115+
[`-CaseSensitive`][12] switch. Comparison of `[char]` types is case-sensitive
116+
by default. String comparison is case-insensitive by default.
117+
118+
```powershell
119+
# Compare strings - Equal (no output)
120+
Compare-object -ReferenceObject a -DifferenceObject A
121+
# Compare chars - Different (output)
122+
Compare-object -ReferenceObject ([char] 'a') -DifferenceObject ([char] 'A')
123+
```
124+
125+
- [`ConvertFrom-Json -AsHashtable`][13]:
126+
- `-AsHashtable` was added in PS v6. In PS v7.3, a change was made to treat
127+
JSON keys as case-sensitive when this parameter is specified.
128+
- With the parameter, an object of type
129+
[`Management.Automation.OrderedHashtable`][27] is emitted, which has
130+
case-sensitive keys.
131+
- Without the parameter, JSON keys are treated as case-insensitive. Output
132+
is a custom object; last case-insensitive key wins.
133+
- https://github.com/PowerShell/PowerShell/issues/19928
134+
135+
- [`Group-Object`][16]:
136+
- Case-insensitive by default, but does have a [`-CaseSensitive`][18]
137+
switch.
138+
- In Windows PowerShell v5.1, `-CaseSensitive` and [`-AsHashtable`][17]
139+
produces a case-insensitive hashtable. Duplicate keys result in an error.
140+
141+
```powershell
142+
[pscustomobject] @{ Foo = 'Bar' }, [pscustomobject] @{ Foo = 'bar' } |
143+
Group-Object -Property Foo -CaseSensitive -AsHashtable
144+
```
145+
146+
```Output
147+
Group-Object : The objects grouped by this property cannot be expanded
148+
because there is a key duplication. Provide a valid value for the
149+
property, and then try again.
150+
At line:2 char:11
151+
+ Group-Object -Property Foo -CaseSensitive -AsHashtable
152+
+ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
153+
+ CategoryInfo : InvalidArgument: (:) [Group-Object], Exception
154+
+ FullyQualifiedErrorId : The objects grouped by this property
155+
cannot be expanded because there is a key duplication. Provide a valid
156+
value for the property, and then try again.,Microsoft.PowerShell.Comman
157+
ds.GroupObjectCommand
158+
```
159+
160+
- In PowerShell v7 and higher, `-CaseSensitive` and `-AsHashtable` produces a
161+
case-sensitive hashtable. No error occurs with duplicate keys.
162+
163+
```powershell
164+
[pscustomobject] @{ Foo = 'Bar' }, [pscustomobject] @{ Foo = 'bar' } |
165+
Group-Object -Property Foo -CaseSensitive -AsHashtable
166+
```
167+
168+
```Output
169+
Name Value
170+
---- -----
171+
Bar {@{Foo=Bar}}
172+
bar {@{Foo=bar}}
173+
```
174+
175+
- [`Select-String`][22]:
176+
- Case-insensitive by default, but does have a [`-CaseSensitive`][23] switch.
177+
178+
- [`Get-Command`][14] and command discovery/invocation:
179+
- On case-sensitive file systems, discovery and invocation of
180+
`ExternalScript` and `Application` command are case-sensitive.
181+
- `Get-Command` wildcard matching with these types is also case-sensitive.
182+
- All other [`CommandTypes`][26] are case-insensitive.
183+
184+
- [Comparison operators][03]:
185+
- By default, operators are case-insensitive.
186+
- `-c*` operators are case-sensitive.
187+
- `-i*` operators are case-insensitive.
188+
- `-replace`/`-ireplace` is case-insensitive by default, _except_ with [named
189+
capture groups][01], which are case-sensitive.
190+
191+
```powershell
192+
'Bar' -replace '(?<a>a)', '${a}${a}'
193+
# Baar
194+
195+
'Bar' -replace '(?<a>a)', '${A}${A}'
196+
# B${A}${A}r
197+
```
198+
199+
- [`-split` operator][10]:
200+
- `-split` and `-isplit` are case-insensitive.
201+
- `-csplit` is case-sensitive, _unless_ the `IgnoreCase` option is specified.
202+
203+
```powershell
204+
'Bar' -csplit 'A', 0
205+
# Bar
206+
207+
'Bar' -csplit 'A', 0, 'IgnoreCase'
208+
# B
209+
# r
210+
```
211+
212+
- [Tab completion][07]:
213+
- On case-sensitive file systems, tab completion and globbing are both
214+
case-insensitive. For example, `TabExpansion2 -inputScript ./foo` will
215+
complete to `./Foo.txt` on Linux.
216+
217+
- [`using`][08] statement:
218+
- On case-sensitive file systems, `using module` and `using assembly` are
219+
case-sensitive when a path is specified.
220+
- `using module` with just a module name is case-insensitive.
221+
- `using namespace` is always case-insensitive.
222+
223+
- [Special characters][06]:
224+
- Escape sequences like `` `n `` are case-sensitive.
47225
48226
## See also
49227
50-
- [about_Environment_Variables](about_Environment_Variables.md)
51-
- [Import-Module](xref:Microsoft.PowerShell.Core.Import-Module)
228+
- [about_Environment_Variables][04]
229+
- [Import-Module][19]
230+
231+
<!-- link references -->
232+
[01]: /dotnet/standard/base-types/substitutions-in-regular-expressions#substituting-a-named-group
233+
[02]: /powershell/scripting/developer/provider/provider-cmdlets
234+
[03]: about_comparison_operators.md
235+
[04]: about_Environment_Variables.md
236+
[05]: about_providers.md
237+
[06]: about_special_characters.md
238+
[07]: about_tab_expansion.md
239+
[08]: about_using.md
240+
[09]: about_wildcards.md
241+
[10]: about_split.md
242+
[11]: xref:Microsoft.PowerShell.Utility.Compare-Object
243+
[12]: xref:Microsoft.PowerShell.Utility.Compare-Object#-casesensitive
244+
[13]: xref:Microsoft.PowerShell.Utility.ConvertFrom-Json#-ashashtable
245+
[14]: xref:Microsoft.PowerShell.Core.Get-Command
246+
[15]: xref:Microsoft.PowerShell.Utility.Get-Unique
247+
[16]: xref:Microsoft.PowerShell.Utility.Group-Object
248+
[17]: xref:Microsoft.PowerShell.Utility.Group-Object#-ashashtable
249+
[18]: xref:Microsoft.PowerShell.Utility.Group-Object#-casesensitive
250+
[19]: xref:Microsoft.PowerShell.Core.Import-Module
251+
[20]: xref:Microsoft.PowerShell.Utility.Select-Object#-caseinsensitive
252+
[21]: xref:Microsoft.PowerShell.Utility.Select-Object#-unique
253+
[22]: xref:Microsoft.PowerShell.Utility.Select-String
254+
[23]: xref:Microsoft.PowerShell.Utility.Select-String#-casesensitive
255+
[24]: xref:Microsoft.PowerShell.Utility.Sort-Object#-casesensitive
256+
[25]: xref:Microsoft.PowerShell.Utility.Sort-Object#-unique
257+
[26]: xref:System.Management.Automation.CommandTypes
258+
[27]: xref:System.Management.Automation.OrderedHashtable

0 commit comments

Comments
 (0)