diff -r 6ce95a04999d -r 2dcced388cab doc/hg.1.txt --- a/doc/hg.1.txt Mon Jun 27 23:52:31 2005 -0800 +++ b/doc/hg.1.txt Mon Jun 27 23:58:07 2005 -0800 @@ -53,17 +53,22 @@ -------- add [files ...]:: - Add the given files to the repository. Note that this just schedules the - files for addition at the next hg commit time. + Schedule files to be version controlled and added to the repository. + + The files get effectively added to the repository at the next commit. addremove:: - Add all new files and remove all missing files from the repository. New - files are ignored if they match any of the patterns in .hgignore + Add all new files and remove all missing files from the repository. + + New files are ignored if they match any of the patterns in .hgignore. As + with add, the effects of this command take place at the next commit. annotate [-r -u -n -c] [files ...]:: - List the files with each line showing the revision id responsible - for that line. - + List changes in files, showing the revision id responsible for each line + + This command is useful to discover who did a change or when a change took + place. + options: -r, --revision annotate the specified revision -u, --user list the author @@ -71,10 +76,105 @@ -n, --number list the revision number (default) cat [revision]:: - Output the given revision or tip of the specified file to stdout. + Output to stdout the given revision for the specified file. + + In case no revision is given, then the tip is used. clone [-U] [dest]:: - Create a new copy of an existing repository. + Create a copy of an existing repository in a new directory. + + If the destination directory is specified, but doesn't exist, it is + created. If no destination directory is specified, it defaults to the + current directory. + + The source is added to the new copy's .hg/hgrc file to be used in + future pulls. + + For speed and storage size, hardlinks are used to do the copy whenever + the specified source and destination are on the same filesystem. + + options: + -U, --no-update do not update the new working directory + +commit [-A -t -l -t -u -d ] [files...]:: + Incorporate changes from given files into the repository. + + If a list of files is ommited, all of the working dir files will + be commited. + + The EDITOR environment variable is used to bring up an editor to add + a commit comment. + + Options: + + -A, --addremove run addremove during commit + -t, --text use as commit message + -l, --logfile show the commit message for the given file + -d, --date record datecode as commit date + -u, --user record user as commiter + + aliases: ci + +copy :: + Mark file as a copy or rename of a one + + This command takes effect for the next commit. + +diff [-r revision] [-r revision] [files ...]:: + Show differences between revisions for the specified files. + + Differences between files are shown using the unified diff format. + + When two revision arguments are given, then changes are shown between + such revisions. If only one revision is specified then that revision is + compared to the tip, and, when no revisions are specified, the working + directory files are compared to the tip. + +export [revision]:: + Print the changeset header and diffs for a particular revision. + + The information shown in the changeset header is: author, changeset hash, + parent and commit comment. + +forget [files]:: + Undo an 'hg add' scheduled for the next commit. + +heads:: + Show all repository head changesets. + + Repository "heads" are changesets that don't have children changesets. + They are where development generally takes place and are the usual targets + for update and merge operations. + +history:: + Print a log of the revision history of the repository. + + By default this command outputs: changeset id and hash, tags, parents, + user, date and time, and a summary for each commit. + The -v switch adds some more detail, such as changed files, manifest + hashes or message signatures. + + To display the history of a given file, see the log command. + +identify:: + Print a short summary of the current state of the repo. + + This summary identifies the repository state using one or two parent + hash identifiers, followed by a "+" if there are uncommitted changes + in the working directory, followed by a list of tags for this revision. + + aliases: id + +import [-p -b -q] :: + Import a list of patches and commit them individually. + + options: + -p, --strip directory strip option for patch. This has the same + meaning as the correnponding patch option + -b base directory to read patches from + + aliases: patch + If the specified source is on the same filesystem, the repository will be copied via hardlinks. This is the fastest and most @@ -91,88 +191,40 @@ options: -U, --no-update do not update the new working directory -commit [-A -t -l -t -u -d ] [files...]:: - Commit all changed files in the working dir to the repository. This uses - the EDITOR environment variable to bring up an editor to add a commit - comment. - - Options: - - -A, --addremove run addremove during commit - -t, --text use as commit message - -l, --logfile read the commit message from the specified - file - -d, --date use the specified date code - -u, --user record commit as the specified user - - aliases: ci - -copy :: - Mark a file as copied or renamed for the next commit. - -diff [-r revision] [-r revision] [files ...]:: - Generate a unified diff of the indicated files. If there are no - revisions specified, the working directory file is compared to - the tip, one revision specified indicates a comparison between the - working directory file and the specified revision, and two revisions - compares the two versions specified. - -export [revision]:: - Print the changeset header (author, changeset hash, parent, and commit - comment) and the diffs for a particular revision. - -forget [files]:: - Undo an 'hg add' scheduled for the next commit. - -heads:: - Show all changesets with no children. These are the "heads" of - development branches and are the usual targets for updates and merges. - -history:: - Print the revision history of the repository. Use the -v switch - for more detail. - -identify:: - Print a short identifier of the current state of the repo. This - includes one or two parent hash identifiers, followed by - a "+" if there are uncommitted changes in the working directory, - followed by a list of tags for this revision. - - aliases: id - -import [-p -b -q] :: - Import the listed patches and commit them individually. - - options: - -p, --strip directory strip option for patch - -b base directory to read patches from - - aliases: patch - init:: Initialize a new repository in the current directory. log :: Print the revision history of the specified file. + To display the revision history for the whole repository, use the history + command. + manifest [revision]:: - Print the indicated revision of the manifest (list of version controlled - files). + Print a list of version controlled files for the given revision. + + The manifest is the list of files being version controlled. If no revision + is given then the tip is used. parents:: Print the working directory's parent revisions. pull :: - Pull any changes from the specified repository to the repository in the - current directory. + Pull any changes from a repository to the current directory's one. + + Pulling is a fundamental operation in a distributed version control system, + as it eases handling changes from different branches, both local and + remote, into the current repository. options: -u, --update update the working directory to tip after pull push :: - Push changes from the local repository to the specified - destination. If the destination is local, this is identical to a - a pull in that directory from the current directory. + Push changes from the local repository to the given destination. + + This is the symmetrical operation for pull. It helps to move changes from + the current repository to a different one. If the destination is local + this is identical to a pull in that directory from the current one. The other currently available push method is SSH. This requires an accessible shell account on the destination machine and a copy of @@ -182,15 +234,22 @@ ssh://[user@]host[:port]/path rawcommit [-p -d -u -F -t -l]:: - Primarily useful for importing from other SCMs. + Lowlevel commit, for use in helper scripts. + + This command is not intended to be used by normal users, as it is + primarily useful for importing from other SCMs. recover:: - Recover from an interrupted commit or pull. This should only be - necessary when Mercurial suggests it. + Recover from an interrupted commit or pull. + + This command tries to fix the repository status after an interrupted + operation. It should only be necessary when Mercurial suggests it. remove [files ...]:: - Schedule the indicated files for removal from the repository at the next - commit. + Schedule the indicated files for removal from the repository. + + This command shedules the files to be removed, but the actual removing + takes place at the next commit. aliases: rm @@ -209,14 +268,27 @@ status:: Show changed files in the working directory. + The codes used to show the status of files are: + C = changed A = added R = removed ? = not tracked tag [-t -d -u ] [revision]:: - Add a tag to the specified revision or the tip. + Name a particular revision using . + + Tags are used to name particular revisions of the repository and are + very useful to compare different revision, to go back to significant + earlier versions or to set special branch points, as releases, etc. + + If no revision is given as argument the tip is used. + This tags are versioned, and kept along with the repository metadata. But + Mercurial has support for other type of tags that can be used locally for + convenience and that are created adding lines with a changeset hash value + and a name or names to name the revision in a .hgtags file + options: -t, --text message for tag commit log entry -d, --date datecode for commit @@ -225,6 +297,8 @@ tags:: List the repository tags. + Local tags in the .hgtags don't get listed when using this command. + tip:: Show the tip revision. @@ -232,22 +306,21 @@ Undo the last commit or pull transaction. update [-m -C] [revision]:: - Update or merge the working directory to a specified revision. - - If there are no outstanding changes in the working directory and - there is a linear relationship between the current version and the - requested version, the result is the requested version. + Bring the working directory to the state of a given revision. - Otherwise the result is a merge between the contents of the - current working directory and the requested version. Files that - changed between either parent are marked as changed for the next - commit and a commit must be performed before any further updates - are allowed. Merging will not be performed without the -m flag. - - The -C switch will tell Mercurial to forcibly update to the - specified version, adding, removing, and overwriting locally - changed fils as necessary. - + After running this command the current directory will have the contents + of the specified revision. + + If there were outstanding changes in the current directory and a merge + would be needed, the -m option can be used to merge those changes with + the target revision. Without the -m or --merge option, no merge + will happen. + + The -C or --clean option must be used in case a pristine version is + desired. In this case, existing changes will be discarded and lost. If + these changes should be kept, then a commit prior updating, or a merge + is due. + options: -m, --merge allow merging of branches -C, --clean overwrite locally modified files