hg-remove

Remove files or directories from the staging area

$ hg remove [path/to/file]

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

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

$ hg remove [[-S|--subrepos]]

$ hg remove [[-A|--after]]

hg remove [-A] [-f] [-I PATTERN] [-X PATTERN] [-n] [-S] FILE...

-A, --after
    Mark files as removed after a successful commit. This option is DEPRECATED and effectively makes hg remove behave like hg forget, meaning the files are assumed to be already deleted from the working directory and their removal is just registered.

-f, --force
    Force removal of files, even if they have uncommitted changes. Using this option will discard any unsaved modifications to the file.

-I PATTERN, --include PATTERN
    Include only names matching the specified pattern for removal. This pattern can be a shell-style glob or a regular expression.

-X PATTERN, --exclude PATTERN
    Exclude names matching the specified pattern from removal. This pattern can be a shell-style glob or a regular expression.

-n, --dry-run
    Do not perform any actual file operations; instead, just print what files would be removed. This is useful for previewing changes before execution.

-S, --subrepos
    Recurse into subrepositories when looking for files to remove, applying the removal operation within them.

The hg remove (or its alias hg rm) command is a fundamental operation in Mercurial used to mark one or more files for deletion from the repository. When invoked, it typically performs two primary actions:

1. It deletes the specified files from your working directory.
2. It marks these files as scheduled for removal in the repository's history, which will be finalized upon the next hg commit.

By default, hg remove will prevent the deletion of files that have uncommitted changes in the working directory to prevent accidental data loss. To override this safeguard, the --force option can be used. For scenarios where a file has been manually deleted from the working directory but is still tracked by the repository, hg remove can be used to formally register its removal with Mercurial.

It's crucial to understand that the actual removal from the repository's history is only confirmed when you perform a subsequent hg commit. Before this, the changes are merely staged for removal. If your intent is to stop tracking a file without physically deleting it from your working directory, the hg forget command is the recommended tool, as the hg remove -A (or --after) option is deprecated for this purpose.

1. Working Directory Deletion: By default, hg remove permanently deletes files from your working directory. Always ensure you have backups or are certain about the removal before proceeding.
2. Requires Commit: The file's removal is not recorded in the repository's history until you perform a subsequent hg commit. Until then, the file might still exist in previous revisions.
3. Uncommitted Changes: Files with uncommitted modifications cannot be removed without the --force option, which will discard those changes.
4. Deprecated Option: The -A / --after option is deprecated. For merely stopping tracking a file without deleting it from the working copy, hg forget is the recommended command.

Unlike the standard Linux rm command, which only deletes files from the file system, hg remove interacts with the Mercurial repository. It not only deletes the file from your working directory but also stages this deletion as a change to be committed to the version control system. This ensures that the file's removal is tracked and becomes a part of the project's historical record.

If you have executed hg remove but have not yet committed the changes, you can typically undo the operation using hg revert FILE. This command will restore the file to its state prior to the removal and also remove the 'deleted' status from Mercurial's pending changes.

hg remove has been a core command in Mercurial since its early development, providing the essential functionality to manage the removal of tracked files from a project's version control. Its alias hg rm offers familiar syntax for users accustomed to Unix-like command-line interfaces. Over time, the Mercurial command set has evolved, leading to the deprecation of certain options, such as -A / --after, in favor of more specialized and clearly defined commands like hg forget, which explicitly separates the act of untracking a file from its physical deletion from the working directory.

hg add(1), hg commit(1), hg revert(1), hg status(1), hg forget(1)