Loop (files & folders)

Retrieves the specified files or folders, one at a time.

New Syntax [v1.1.21+]

Loop, Files, FilePattern , Mode

Parameters

Files

The literal word Files (case-insensitive). This cannot be a variable or expression.

FilePattern

The name of a single file or folder, or a wildcard pattern such as C:\Temp\*.tmp. FilePattern is assumed to be in A_WorkingDir if an absolute path isn't specified.

Both asterisks and question marks are supported as wildcards. A match occurs when the pattern appears in either the file's long/normal name or its 8.3 short name.

If this parameter is a single file or folder (i.e. no wildcards) and Mode includes R, more than one match will be found if the specified file name appears in more than one of the folders being searched.

Mode

Zero or more of the following letters:

D: Include directories (folders).
F: Include files. If both F and D are omitted, files are included but not folders.
R: Recurse into subdirectories (subfolders). If R is omitted, files and folders in subfolders are not included.

Old Syntax

Deprecated: This syntax is not recommended for use in new scripts. Use the new syntax instead.

Loop, FilePattern , IncludeFolders?, Recurse?

Parameters

FilePattern

The name of a single file or folder, or a wildcard pattern such as C:\Temp\*.tmp. FilePattern is assumed to be in %A_WorkingDir% if an absolute path isn't specified.

Both asterisks and question marks are supported as wildcards. A match occurs when the pattern appears in either the file's long/normal name or its 8.3 short name.

If this parameter is a single file or folder (i.e. no wildcards) and Recurse is set to 1, more than one match will be found if the specified file name appears in more than one of the folders being searched.

IncludeFolders?

One of the following digits, or blank to use the default:
0 (default) Folders are not retrieved (only files).
1 All files and folders that match the wildcard pattern are retrieved.
2 Only folders are retrieved (no files).

Recurse?

One of the following digits, or blank to use the default:
0 (default) Subfolders are not recursed into.
1 Subfolders are recursed into so that files and folders contained therein are retrieved if they match FilePattern. All subfolders will be recursed into, not just those whose names match FilePattern.

Special Variables Available Inside a File-Loop

The following variables exist within any file-loop. If an inner file-loop is enclosed by an outer file-loop, the innermost loop's file will take precedence:

Loop, C:\My Documents\Address List.txt
    ShortPathName = %A_LoopFileShortPath%

Remarks

A file-loop is useful when you want to operate on a collection of files and/or folders, one at a time.

All matching files are retrieved, including hidden files. By contrast, OS features such as the DIR command omit hidden files by default. To avoid processing hidden, system, and/or read-only files, use something like the following inside the loop:

if A_LoopFileAttrib contains H,R,S  ; Skip any file that is either H (Hidden), R (Read-only), or S (System). Note: No spaces in "H,R,S".
    continue  ; Skip this file and move on to the next one.

To retrieve files' relative paths instead of absolute paths during a recursive search, use SetWorkingDir to change to the base folder prior to the loop, and then omit the path from the Loop (e.g. Loop, *.*, 0, 1). That will cause A_LoopFileFullPath to contain the file's path relative to the base folder.

A file-loop can disrupt itself if it creates or renames files or folders within its own purview. For example, if it renames files via FileMove or other means, each such file might be found twice: once as its old name and again as its new name. To work around this, rename the files only after creating a list of them. For example:

FileList =
Loop, Files, *.jpg
    FileList = %FileList%%A_LoopFileName%`n
Loop, Parse, FileList, `n
    FileMove, %A_LoopField%, renamed_%A_LoopField%

Files in an NTFS file system are probably always retrieved in alphabetical order. Files in other file systems are retrieved in no particular order. To ensure a particular ordering, use the Sort command as shown in the Examples section below.

Files and folders with a complete path name longer than 259 characters are skipped over as though they do not exist. Such files are rare because normally, the operating system does not allow their creation.

See Loop for information about Blocks, Break, Continue, and the A_Index variable (which exists in every type of loop).

Related

Loop, Break, Continue, Blocks, SplitPath, FileSetAttrib, FileSetTime

Examples

; Example #1:
Loop Files, %A_ProgramFiles%\*.txt, R  ; Recurse into subfolders.
{
    MsgBox, 4, , Filename = %A_LoopFileFullPath%`n`nContinue?
    IfMsgBox, No
        break
}

; Example #2: Calculate the size of a folder, including the files in all its subfolders:
SetBatchLines, -1  ; Make the operation run at maximum speed.
FolderSizeKB = 0
FileSelectFolder, WhichFolder  ; Ask the user to pick a folder.
Loop, Files, %WhichFolder%\*.*, R
    FolderSizeKB += %A_LoopFileSizeKB%
MsgBox Size of %WhichFolder% is %FolderSizeKB% KB.

; Example #3: Retrieve file names sorted by name (see next example to sort by date):
FileList =  ; Initialize to be blank.
Loop, C:\*.*
    FileList = %FileList%%A_LoopFileName%`n
Sort, FileList, R  ; The R option sorts in reverse order. See Sort for other options.
Loop, parse, FileList, `n
{
    if A_LoopField =  ; Ignore the blank item at the end of the list.
        continue
    MsgBox, 4,, File number %A_Index% is %A_LoopField%.  Continue?
    IfMsgBox, No
        break
}

; Example #4: Retrieve file names sorted by modification date:
FileList =
Loop, Files, %A_MyDocuments%\Photos\*.*, FD  ; Include Files and Directories
    FileList = %FileList%%A_LoopFileTimeModified%`t%A_LoopFileName%`n
Sort, FileList  ; Sort by date.
Loop, Parse, FileList, `n
{
    if A_LoopField =  ; Omit the last linefeed (blank item) at the end of the list.
        continue
    StringSplit, FileItem, A_LoopField, %A_Tab%  ; Split into two parts at the tab char.
    MsgBox, 4,, The next file (modified at %FileItem1%) is:`n%FileItem2%`n`nContinue?
    IfMsgBox, No
        break
}

; Example #5: Copy only the source files that are newer than their counterparts
; in the destination:
CopyIfNewer:
; Caller has set the variables CopySourcePattern and CopyDest for us.
Loop, Files, %CopySourcePattern%
{
    copy_it = n
    IfNotExist, %CopyDest%\%A_LoopFileName%  ; Always copy if target file doesn't yet exist.
        copy_it = y
    else
    {
        FileGetTime, time, %CopyDest%\%A_LoopFileName%
        EnvSub, time, %A_LoopFileTimeModified%, seconds  ; Subtract the source file's time from the destination's.
        if time < 0  ; Source file is newer than destination file.
            copy_it = y
    }
    if copy_it = y
    {
        FileCopy, %A_LoopFileFullPath%, %CopyDest%\%A_LoopFileName%, 1   ; Copy with overwrite=yes
        if ErrorLevel
            MsgBox, Could not copy "%A_LoopFileFullPath%" to "%CopyDest%\%A_LoopFileName%".
    }
}
Return

; Example #6: Convert filenames passed in via command-line parameters to long names,
; complete path, and correct uppercase/lowercase characters as stored in the file system.
Loop %0%  ; For each file dropped onto the script (or passed as a parameter).
{
    GivenPath := %A_Index%  ; Retrieve the next command line parameter.
    Loop %GivenPath%, 1
        LongPath = %A_LoopFileLongPath%
    MsgBox The case-corrected long path name of file`n%GivenPath%`nis:`n%LongPath%
}