How to use the command 'hg add' (with examples)

The hg add command is used in Mercurial (Hg) to add specified files to the staging area for the next commit. This command is essential when you want to include specific changes in your next commit.

Use case 1: Add files or directories to the staging area

Code:

hg add path/to/file

Motivation: You have made changes to a specific file or directory and want to include these changes in your next commit.

Explanation: The hg add command followed by the path to the file or directory adds it to the staging area. This allows you to include the changes in the next commit.

Example output:

adding path/to/file

Use case 2: Add all unstaged files matching a specified pattern

Code:

hg add --include pattern

Motivation: You have multiple files that match a specific pattern and you want to include all of them in the staging area without manually specifying each file.

Explanation: The --include option followed by the pattern allows you to specify a pattern to match a set of files. The hg add command will then add all unstaged files that match the specified pattern to the staging area.

Example output:

adding file1.txt
adding file2.txt
adding file3.txt

Use case 3: Add all unstaged files, excluding those that match a specified pattern

Code:

hg add --exclude pattern

Motivation: You have multiple files in the repository and you want to add all unstaged files to the staging area, except for those that match a specific pattern.

Explanation: The --exclude option followed by the pattern allows you to specify a pattern to exclude certain files from being added to the staging area. The hg add command will add all unstaged files to the staging area, excluding those that match the specified pattern.

Example output:

adding file1.txt
adding file2.txt

Use case 4: Recursively add sub-repositories

Code:

hg add --subrepos

Motivation: Your repository contains sub-repositories (submodules) and you want to add changes from all the sub-repositories to the staging area.

Explanation: The --subrepos option tells the hg add command to recursively add sub-repositories as well. This means that any changes you made in the sub-repositories will also be added to the staging area.

Example output:

adding sub-repo1/file1.txt
adding sub-repo1/file2.txt
adding sub-repo2/file1.txt

Use case 5: Perform a test-run without performing any actions

Code:

hg add --dry-run

Motivation: You want to check what files would be added to the staging area without actually modifying anything.

Explanation: The --dry-run option allows you to perform a test-run of the hg add command without actually adding files to the staging area. It provides a list of files that would be added if the command were run without the --dry-run option.

Example output:

adding path/to/file
adding file1.txt

Conclusion:

The hg add command in Mercurial is a powerful tool to add specific changes to the staging area for the next commit. Whether you want to add individual files, files matching a pattern, or even recursively add sub-repositories, the hg add command gives you the flexibility to include exactly what you need. By understanding the different use cases, you can effectively manage your changes and ensure that each commit accurately reflects your intentions.