hg-add

Add files or directories to the staging area

$ hg add [path/to/file]

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

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

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

$ hg add [[-n|--dry-run]]

hg add [OPTION]... [FILE | DIRECTORY]...
hg add --all

[FILE | DIRECTORY]...
    Specifies individual files or directories to add. If a directory is provided, all new files and subdirectories within it are added recursively.

--all, -A
    Adds all untracked files in the current repository. This option also automatically marks missing files for removal (equivalent to hg rm).

--include PATTERN, -I PATTERN
    Includes names matching the given pattern. Can be specified multiple times.

--exclude PATTERN, -X PATTERN
    Excludes names matching the given pattern. Can be specified multiple times.

--subrepos, -S
    Operates on untracked subrepositories, adding them to the parent repository's tracking.

--dry-run, -n
    Displays what files would be added without actually performing the operation.

The hg add command marks one or more files or directories for inclusion in the Mercurial repository's tracking system. When new files are created within a repository, Mercurial does not automatically track them. You must explicitly tell Mercurial to start tracking these files using hg add. Once added, the files are staged for the next commit. This command does not modify the repository history directly; it merely prepares the files for the subsequent hg commit operation. It's crucial for bringing new content under version control, allowing Mercurial to monitor changes and enable future operations like branching, merging, and reverting. It's a core command for any new content.

Files are not committed immediately; a subsequent hg commit is required to save changes to the repository history.
hg add only tracks new files; to track modifications to existing files, simply make changes and then hg commit them.
Using --all can also stage files for removal if they are tracked but missing from the working directory, which might be an unintended side effect if not carefully used.

You can add multiple files by listing them individually (e.g., hg add file1.txt file2.txt) or by specifying a directory (e.g., hg add mydir/).
The --all option is a convenient shortcut for adding all newly created files in a project without specifying each one.

Before using hg add, it's often useful to configure a .hgignore file. This file specifies patterns for files and directories that Mercurial should ignore, preventing them from being listed as untracked or accidentally added to the repository. Files matched by .hgignore are not considered by hg add --all.

hg add is a fundamental command in Mercurial, a distributed version control system created by Matt Mackall in 2005 as an alternative to BitKeeper. It has been a core part of Mercurial's workflow since its inception, mirroring similar functionality found in other VCS like Git's git add. Its design reflects Mercurial's philosophy of explicit action for version control operations, requiring users to explicitly stage new files before committing them to the repository.

hg commit(1), hg status(1), hg rm(1), hg forget(1), hg mv(1)