LinuxCommandLibrary

hg-add

Add files to Mercurial repository

TLDR

Add files or directories to the staging area

$ hg add [path/to/file]
copy

Add all unstaged files matching a specified pattern
$ hg add [[-I|--include]] [pattern]
copy

Add all unstaged files, excluding those that match a specified pattern
$ hg add [[-X|--exclude]] [pattern]
copy

Recursively add sub-repositories
$ hg add [[-S|--subrepos]]
copy

Perform a test-run without performing any actions
$ hg add [[-n|--dry-run]]
copy

SYNOPSIS

hg add [OPTION]... [FILE]...

PARAMETERS

-n, --dry-run
    Don't perform any actions, just print output.

-I PATTERN, --include PATTERN
    Include names matching the given pattern. May be specified multiple times; all patterns must match.

-X PATTERN, --exclude PATTERN
    Exclude names matching the given pattern. May be specified multiple times; none of the patterns must match.

--config SECTION.NAME=VALUE
    Set configuration option

[FILE]...
    Files or directories to add. If no files are specified, Mercurial will try to add all untracked files in the current directory and subdirectories.

DESCRIPTION

The hg add command in Mercurial (hg) is used to tell Mercurial to start tracking new files. Mercurial only tracks files that are explicitly added to the repository. This command stages files for inclusion in the next commit.
It's crucial to understand that hg add doesn't immediately record changes; it merely flags the files to be included in the subsequent commit. Without using hg add, new files will be ignored by Mercurial, and their changes won't be tracked.
Often, after adding files, you'll want to use hg commit to create a changeset that includes the newly added files.

CAVEATS

The hg add command only adds files that are not already tracked by Mercurial. To update changes to tracked files, you would generally modify the file, then use hg commit to record the changes. To handle the case when a file was renamed use hg rename

UNDERSTANDING .HGIGNORE

Mercurial relies on the .hgignore file to automatically exclude certain files and patterns from being tracked. Make sure you add all necessary patterns to the .hgignore file before using hg add, it will save you time later.

ADDING LARGE FILES

While Mercurial can handle large files, storing extremely large binary files directly in the repository might not be the most efficient approach. Consider using Mercurial's largefiles extension or external storage solutions for very large assets.

HISTORY

The hg add command has been part of Mercurial since its inception. It's a fundamental command for managing files under version control. Its core functionality has remained consistent, but Mercurial's pattern matching capabilities and configuration options have evolved over time, affecting how hg add can be used to include or exclude files.

SEE ALSO

hg commit(1), hg status(1), hg remove(1), hg rename(1)

Copied to clipboard