You wanted to know whether a file name contains log. You wrote 'error.log' -contains 'log', got False, and started doubting your eyes. A few lines later, if ($values -eq 0) skipped a list that clearly has a zero in it.
Both bugs come from the same misunderstanding. -contains is not a substring check. It asks "is this exact item in this collection?" And -eq with an array on the left does not return True or False. It returns the matching items, and that result can be falsy even when a match exists.
Everything below was run in PowerShell 7.4 (7.4.6), and the output shown is the real output. The same rules apply in Windows PowerShell 5.1.
The shortest honest comparison
-eq |
-contains |
|
|---|---|---|
| Question it asks | "Is this equal to that?" | "Is this item in the collection?" |
| Scalar on the left | Returns True / False
|
Treats the left side as a one-item collection |
| Array on the left | Returns the matching items (a filter) | Returns True / False
|
| Substring check | No | No (use -like or .Contains()) |
| Wildcards | No | No |
| Case-sensitive version | -ceq |
-ccontains |
| Mirror operator | (none) |
-in (item first, collection second) |
Trap 1: -contains is not "string contains"
'error.log' -contains 'log'
'error.log'.Contains('log')
'error.log' -like '*log*'
False
True
True
'error.log' is a single string, so PowerShell treats it as a collection with one item: 'error.log'. Is the item 'log' in that collection? No. For "does this text include that text", use the string method .Contains() (case-sensitive) or -like with stars on both sides (case-insensitive).
What -contains is actually for
-contains checks membership in a list, item by item, using the same equality rules as -eq:
$allowed = '.log', '.txt', '.csv'
$allowed -contains '.txt'
$allowed -contains '.TXT'
$allowed -ccontains '.TXT'
$allowed -contains '*.txt'
True
True
False
False
Notes on the four results:
-
.txtis in the list, soTrue. -
.TXTis alsoTrue, because-containsignores case by default. -
-ccontainsis the case-sensitive version, so.TXTis not found. -
*.txtisFalse. There are no wildcards here. The star is just a character.
Trap 2: -eq on an array is a filter
Put an array on the left of -eq and you don't get a Boolean back. You get every item that is equal:
$codes = 200, 404, 200, 500
$codes -eq 200
'---'
($codes -eq 200).Count
'---'
$codes -contains 200
200
200
---
2
---
True
$codes -eq 200 returned both 200 values. That is useful when you want the matches (or a count of them). When you only want a yes/no answer, -contains gives you a clean True.
Trap 3: if ($array -eq ...) can be false even when it matches
This one causes real bugs in scripts. Read the conditions and guess the output first:
$values = 0, 1, 2
if ($values -eq 0) { 'found zero' } else { 'no zero?' }
$names = '', 'alice'
if ($names -eq '') { 'found empty name' } else { 'no empty name?' }
no zero?
no empty name?
Both lists contain the value, and both if statements still take the else branch. Here is why:
-
$values -eq 0returns a one-item array:@(0). - PowerShell converts a one-item array to Boolean by looking at that item.
0is falsy, so the whole condition isFalse. - The same happens with
'': a one-item array holding an empty string is falsy.
Switch to -contains and the answer is what you meant:
$values = 0, 1, 2
if ($values -contains 0) { 'found zero' } else { 'no zero' }
$names = '', 'alice'
if ($names -contains '') { 'found empty name' } else { 'no empty name' }
found zero
found empty name
Trap 4: always put $null on the left
Comparing with $null has the same filter behavior, just with the opposite surprise:
$list = 1, $null, 2, $null
if ($list -eq $null) { 'list is null' } else { 'list is not null' }
if ($null -eq $list) { 'list is null' } else { 'list is not null' }
'---'
($list -eq $null).Count
list is null
list is not null
---
2
$list -eq $null returned the two $null items. A two-item array is truthy, so the first if claims the whole list "is null". $null -eq $list asks the question you meant ("is $list itself null?") and correctly says no. This is why PSScriptAnalyzer flags $var -eq $null and recommends $null -eq $var.
-in and -notin: the same check, flipped
-in is -contains with the operands swapped. Many people find it reads more naturally in a Where-Object filter:
$allowed = '.log', '.txt', '.csv'
'.txt' -in $allowed
'.exe' -in $allowed
'.exe' -notin $allowed
$allowed -notcontains '.exe'
True
False
True
True
'.txt' -in $allowed and $allowed -contains '.txt' mean the same thing. Pick whichever order reads better in your script, and stay consistent.
Type conversion follows the left side
PowerShell converts the right-hand value to the type of the left-hand value before comparing. With -contains, each item in the collection plays the "left" role:
1, 2, 3 -contains '2'
'1', '2', '3' -contains 2
'---'
1 -eq '01'
'01' -eq 1
True
True
---
True
False
1 -eq '01' is True because '01' is converted to the number 1. '01' -eq 1 is False because 1 becomes the string '1', which isn't '01'. If you compare IDs or version-like strings, make sure both sides have the type you expect.
Real use: an extension allow list with Get-ChildItem
Here is a practical script that filters files by an allow list and checks that a required file exists. The demo creates its own temp folder and cleans up after itself:
$dir = Join-Path ([IO.Path]::GetTempPath()) 'eq-vs-contains-demo'
New-Item -ItemType Directory -Path $dir -Force | Out-Null
'app.log', 'notes.txt', 'setup.exe', 'data.CSV', 'script.ps1' |
ForEach-Object { New-Item -Path $dir -Name $_ -ItemType File -Force | Out-Null }
$allowed = '.log', '.txt', '.csv'
# Keep only files whose extension is on the allow list
Get-ChildItem $dir -File |
Where-Object { $allowed -contains $_.Extension } |
Select-Object -ExpandProperty Name
'---'
# Check a required file exists before you continue
$names = (Get-ChildItem $dir -File).Name
if ($names -contains 'config.json') { 'config found' } else { 'config.json is missing' }
Remove-Item $dir -Recurse -Force
app.log
data.CSV
notes.txt
---
config.json is missing
data.CSV passes because -contains ignores case, and setup.exe and script.ps1 are filtered out. The second check gives a clean yes/no about a required file without any substring surprises.
If you want to try these checks without setting anything up, CMD Master's free interactive PowerShell course in the browser gives you a real terminal to experiment in.
Quick checklist
- "Is this item in my list?": use
-containsor-in. - "Does this text include that text?": use
-like '*text*'or.Contains(), never-contains. - "Which items match?": use
-eqwith the array on the left, orWhere-Object. - Inside an
if, avoid$array -eq $value. A single0,'', or$nullmatch is falsy. - Comparing with
$null: write$null -eq $var. - Need case to matter:
-ceq/-ccontains/-cin. - Mixed types: the left side decides the conversion.
Practice in a real terminal
Comparison operators stick much better once you type them yourself and watch the output. CMD Master is a free, interactive browser terminal for learning CMD, PowerShell, and Bash, with instant feedback on every command and nothing to install.
Sources: Microsoft Learn: about_Comparison_Operators, about_Booleans, Everything you wanted to know about $null, PSPossibleIncorrectComparisonWithNull rule, Where-Object, String.Contains.
Quick quiz
Without running it: what does this output in PowerShell 7.4?
$tags = 'prod', 'Prod', 'dev'
($tags -eq 'PROD').Count
Is it 0, 1, 2, or something else? Drop your answer (and why) in the comments.
Top comments (0)