DEV Community

Cover image for PowerShell -eq vs -contains: The Real Difference (and Why 'error.log' -contains 'log' Is False)
arnostorg
arnostorg

Posted on Edited on

PowerShell -eq vs -contains: The Real Difference (and Why 'error.log' -contains 'log' Is False)

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*'
Enter fullscreen mode Exit fullscreen mode
False
True
True
Enter fullscreen mode Exit fullscreen mode

'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'
Enter fullscreen mode Exit fullscreen mode
True
True
False
False
Enter fullscreen mode Exit fullscreen mode

Notes on the four results:

  • .txt is in the list, so True.
  • .TXT is also True, because -contains ignores case by default.
  • -ccontains is the case-sensitive version, so .TXT is not found.
  • *.txt is False. 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
Enter fullscreen mode Exit fullscreen mode
200
200
---
2
---
True
Enter fullscreen mode Exit fullscreen mode

$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?' }
Enter fullscreen mode Exit fullscreen mode
no zero?
no empty name?
Enter fullscreen mode Exit fullscreen mode

Both lists contain the value, and both if statements still take the else branch. Here is why:

  • $values -eq 0 returns a one-item array: @(0).
  • PowerShell converts a one-item array to Boolean by looking at that item. 0 is falsy, so the whole condition is False.
  • 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' }
Enter fullscreen mode Exit fullscreen mode
found zero
found empty name
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
list is null
list is not null
---
2
Enter fullscreen mode Exit fullscreen mode

$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'
Enter fullscreen mode Exit fullscreen mode
True
False
True
True
Enter fullscreen mode Exit fullscreen mode

'.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
Enter fullscreen mode Exit fullscreen mode
True
True
---
True
False
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode
app.log
data.CSV
notes.txt
---
config.json is missing
Enter fullscreen mode Exit fullscreen mode

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 -contains or -in.
  • "Does this text include that text?": use -like '*text*' or .Contains(), never -contains.
  • "Which items match?": use -eq with the array on the left, or Where-Object.
  • Inside an if, avoid $array -eq $value. A single 0, '', or $null match 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
Enter fullscreen mode Exit fullscreen mode

Is it 0, 1, 2, or something else? Drop your answer (and why) in the comments.

Top comments (0)