hg-commit

Commit staged files to the repository

$ hg commit

$ hg commit [path/to/file_or_directory]

$ hg commit [[-m|--message]] [message]

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

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

$ hg commit [[-i|--interactive]]

hg commit [OPTION]... [FILE]...

-m MESSAGE, --message MESSAGE
    Use the specified MESSAGE as the commit description. If this option is not provided, an editor will be opened for message entry.

-l FILE, --logfile FILE
    Read the commit message from the specified FILE.

-A, --addremove
    Automatically mark all unknown files as added and all missing files as removed before committing. This simplifies committing all changes.

-I PATTERN, --include PATTERN
    Include only files matching the given PATTERN. This option can be used multiple times.

-X PATTERN, --exclude PATTERN
    Exclude files matching the given PATTERN from the commit. This option can be used multiple times.

-S, --subrepos
    Recurse into subrepositories and commit their changes as well. This is useful for projects with nested Mercurial repositories.

-U, --amend
    Amend the previous commit, meaning the current changes will modify the most recent changeset instead of creating a new one. Use with caution, especially after pushing changes to shared repositories.

-d DATE, --date DATE
    Set the date of the commit to the specified DATE. This is typically used for historical commits or specific workflow requirements.

-u USER, --user USER
    Set the author of the commit to the specified USER. This overrides the configured user name.

-f, --force
    Force the commit operation, bypassing some warnings or checks.

-e, --edit
    Always invoke the editor for the commit message, even if --message or --logfile is provided. Useful for reviewing or adding to a predefined message.

-n, --dry-run
    Do not commit changes, but instead show what files would be committed. Useful for verifying the commit scope.

The hg-commit command is a fundamental operation in Mercurial, a distributed version control system. It is used to record changes from the working directory into the repository as a new changeset. A changeset represents a snapshot of the project at a specific point in time and contains the modifications made since the previous commit.

When executed, hg-commit examines the working directory for modified, added, or removed files. By default, if no specific files are provided, it commits all tracked changes. If untracked files are present, they are not committed unless explicitly added (e.g., via hg add or the --addremove option). The command typically opens a text editor for you to compose a commit message, which describes the changes being committed. This message is crucial for understanding the history of the project.

Using the --amend option (`-U`) modifies repository history. This should be done with extreme caution, especially if the changeset has already been shared with other developers or pushed to a public repository, as it can cause conflicts and confusion during future synchronizations.

Mercurial, like other DVCS, can store large binary files. However, committing large files repeatedly without using extensions like largefiles can significantly increase the repository's size and performance overhead for cloning and updating, potentially making operations slow.

A well-crafted commit message is vital for project maintainability and collaboration. It should clearly explain what changes were made and why they were made. Mercurial's default behavior of opening an editor encourages descriptive messages. A common convention is a concise single-line summary (often under 50-72 characters) followed by a blank line and then a more detailed explanation, typically wrapped at 72-80 characters.

Files that should not be tracked by Mercurial (e.g., build artifacts, temporary files, personal IDE settings, sensitive configurations) can be specified in a .hgignore file. This file uses pattern matching to prevent these files from appearing in hg status output and from being accidentally committed, keeping the repository clean and focused on source code.

hg-commit is a core command of Mercurial, a distributed revision control system that originated in 2005. Developed primarily by Matt Mackall, Mercurial was created as a fast, lightweight alternative to older, centralized version control systems, largely in response to BitKeeper's licensing changes. The commit command is central to its workflow, allowing users to bundle discrete changes into atomic units (changesets) that form the project's history. Its design mirrors similar commands in other DVCS like Git, emphasizing local commits before sharing with others.

hg(1), hg status(1), hg diff(1), hg add(1), hg remove(1), hg revert(1), hg push(1), hg pull(1)