hg-status

Display the status of changed files

$ hg status

$ hg status [[-m|--modified]]

$ hg status [[-a|--added]]

$ hg status [[-r|--removed]]

$ hg status [[-d|--deleted]]

$ hg status --rev [revision]

$ hg status [[-I|--include]] [pattern]

$ hg status [[-X|--exclude]] [pattern]

hg status [OPTION]... [FILE]...

FILE...
    Optional filenames or directory paths to limit the status output to specific items.

-A, --added
    Show only files scheduled for addition.

-C, --clean
    Show only clean files (not modified since the last commit).

-D, --deleted
    Show only files scheduled for deletion or removal.

-M, --modified
    Show only files that have been modified.

-U, --unknown
    Show only files not tracked by Mercurial (untracked).

-I, --ignored
    Show only files that are ignored via .hgignore.

-s, --summary
    Print only a summary of file counts by status type.

-r REV, --rev REV
    Show status compared to the specified revision REV instead of the parent of the working directory.

-c REV, --change REV
    Show files that have changed between revision REV and the working directory.

-n, --no-status
    Suppress the leading status characters (e.g., 'M ', 'A '). Only show filenames.

-0, --print0
    End filenames with a null character (NUL) instead of a newline, useful for scripting with tools like xargs -0.

-T STR, --template STR
    Use the given template string STR to format the output for each file.

-X PATTERN, --exclude PATTERN
    Exclude files matching the given pattern PATTERN from the output.

-I PATTERN, --include PATTERN
    Include files matching the given pattern PATTERN in the output (overrides excludes).

-S, --subrepos
    Recurse into subrepositories when checking status.

The hg status command displays the status of files and directories in the working copy compared to the repository's tip. It's a fundamental tool for understanding local changes before committing, providing an immediate snapshot of modifications. By default, it lists files that are modified, added, removed, missing from the working copy, and unknown (untracked). The output is designed to be clear and concise, often color-coded to help users quickly distinguish different file states. This command is crucial for deciding which files to stage for the next commit, which to add or remove, or which to ignore, thus offering an essential overview of the working directory's current state relative to the version control system.

Performance can be slow on very large repositories with a vast number of untracked files, especially without a well-configured .hgignore file. By default, hg status does not automatically recurse into subrepositories unless the -S or --subrepos option is used. The command displays renames or copies as distinct additions and deletions; explicit rename/copy tracking is typically handled by other commands like hg diff or hg log --follow.

The hg status command uses single-character codes at the beginning of each line to indicate the status of a file:

M: Modified (file has been changed)
A: Added (file is scheduled for addition)
R: Removed (file is scheduled for removal)
!: Missing (file has been deleted from the working copy but not yet committed)
?: Unknown (file is not tracked by Mercurial)
C: Clean (file has not been modified; shown only with -C or --clean)
I: Ignored (file matches an .hgignore pattern; shown only with -I or --ignored)
U: Unresolved (file has merge conflicts)

hg status is a core command of Mercurial, a distributed version control system initiated by Matt Mackall in 2005. Designed to provide a clear and immediate overview of the working directory's state, it has been an integral part of Mercurial since its inception. Its simplicity and effectiveness align with Mercurial's broader philosophy of ease of use and clarity, with evolution focusing primarily on output options and formatting rather than its fundamental function.

hg add(1), hg remove(1), hg commit(1), hg diff(1), hg revert(1), hg log(1)