How to Use the Command 'hg status' (with Examples)

The hg status command is an integral part of the Mercurial version control system. It allows developers to quickly discern the state of files in their working directory regarding their repository. With this command, users can identify which files have been modified, added, removed, or deleted, providing critical insights that facilitate efficient source code management. This command’s versatility makes it an essential tool for version control workflows by offering different options to filter and manipulate output based on developers’ needs.

Use Case 1: Display the Status of Changed Files

Code:

hg status

Motivation: The primary reason for using hg status without any arguments is to get a comprehensive overview of all the changes in the working directory. This helps developers identify which files have been altered since the last commit and need attention, making it easier to decide the next steps, be it committing, amending, or reverting changes.

Explanation: This command, in its basic form, displays all files that have undergone any form of change—be it addition, modification, removal, or deletion—relative to the last committed state. It provides a quick audit of the working directory, offering a clear snapshot of its current divergence from the repository.

Example Output:

M file1.txt
A newfile.py
R oldfile.c
! deletedfile.md

• M file1.txt indicates that the file has been modified.
• A newfile.py signifies a newly added file.
• R oldfile.c denotes a file scheduled for removal.
• ! deletedfile.md shows a tracked file that is now missing from the working directory.

Use Case 2: Display Only Modified Files

Code:

hg status --modified

Motivation: Focusing specifically on modified files helps streamline the review process by zeroing in on those files that have been changed but not yet committed. This can be particularly useful in larger projects where numerous files might be added or removed, allowing developers to prioritize code review and testing efforts.

Explanation: The --modified option filters the output to show only files that have been altered since the last commit but are still present in the working directory. This targets files that may need evaluation for changes regarding functionality, code style, or bugs.

Example Output:

M src/main.cpp
M README.md

• Each line indicates files (with a M prefix) that have undergone changes after the last commit.

Use Case 3: Display Only Added Files

Code:

hg status --added

Motivation: Tracking newly added files is crucial for ensuring they are correctly versioned and nothing is left out unintentionally. When preparing changes for a commit, developers can use this command to ensure all newly created files are included, especially in multi-file projects where file additions are frequent.

Explanation: The --added parameter lists only those files that have been added to the working directory but have yet to be committed. This is essential for verifying that all new resources, scripts, or documents are recognized by the version control system before a commit.

Example Output:

A scripts/setup.sh
A docs/manual.pdf

• The output lists files prefixed with A, showing they are new additions to the repository.

Use Case 4: Display Only Removed Files

Code:

hg status --removed

Motivation: Seeing which files are scheduled for removal can help confirm intentional deletions, preventing accidental data loss. It’s a critical step in refactoring or cleaning up obsolete files, ensuring that intended deletions are properly staged before they are committed.

Explanation: The --removed flag results in the display of files that are marked for deletion in the working directory but have not been removed from the repository yet. This step is vital in double-checking that any file deletions align with the intentions of the development or maintenance task.

Example Output:

R unused_module.py
R old_feature/

• File paths with the R prefix indicate they are set for removal in the next commit operation.

Use Case 5: Display Only Deleted (But Tracked) Files

Code:

hg status --deleted

Motivation: Occasionally, files that are no longer present might have been deleted unintentionally. Checking for such files using this option prevents undesired effects like missing resources or broken references, allowing developers to restore them if necessary before finalizing the commit.

Explanation: The --deleted argument shows files that were once tracked but are currently missing from the working directory. It effectively flags any tracked files that have been removed but not through version control commands, prompting users to address these discrepancies.

Example Output:

! images/logo.png
! config/backup.cfg

• Lines with a ! prefix are files previously tracked by the repository but now absent from the working directory.

Use Case 6: Display Changes in the Working Directory Compared to a Specified Changeset

Code:

hg status --rev 1234

Motivation: Comparing the current working directory to a specific historical changeset allows developers to see what has changed since a certain point in the project’s history. This is beneficial when evaluating progress or determining the ramifications of updates against a known state.

Explanation: The --rev option enables users to specify a particular changeset ID (1234 in this case) to compare against the current state of the working directory. It highlights how the current working draft deviates from the specified changeset, useful for targeted reviews and precise regression testing.

Example Output:

M server/api.py
A utils/helpers.py

• Output shows what has changed in the working directory compared to changeset 1234.

Use Case 7: Display Only Files Matching a Specified Glob Pattern

Code:

hg status --include *.py

Motivation: Developers can focus solely on specific types of files, such as Python scripts in this case. This targeted approach simplifies workflows by filtering only relevant files, which is extremely helpful when working on projects with mixed file types.

Explanation: The --include flag, followed by a glob pattern (*.py), limits the output to files matching that pattern. This is an efficient way to handle large directories, ensuring that only files fitting the specified criteria are inspected or manipulated at a time.

Example Output:

M scripts/deploy.py
A scripts/initialize.py

• Only .py files that are modified or new are shown, providing a filtered view for efficient code examination.

Use Case 8: Display Files, Excluding Those that Match a Specified Glob Pattern

Code:

hg status --exclude *.log

Motivation: Excluding specific files or types of files, such as log files, helps reduce noise in the status output. This allows developers to concentrate on source code changes without distraction from automatically generated or non-critical files.

Explanation: With the --exclude option, users can omit files matching a pattern (*.log) from the status output. This is particularly useful when certain files are constantly updated or regenerated but are not pertinent to the current tasks, optimizing the review process.

Example Output:

M src/server.java
R src/client.java

• Log files are ignored in this output, focusing the report on other critical source files.

Conclusion:

The hg status command is a versatile and powerful tool that enables developers to maintain clear oversight of the working directory’s state. By leveraging its various options, users can tailor the command’s output to fit specific needs, ensuring efficient version control workflow and preventing errors related to file tracking and changes. Whether identifying modified files, adding new ones, or verifying removals, hg status helps maintain effective project management and quality assurance in development environments.