Differences between revisions 1 and 34 (spanning 33 versions)
Revision 1 as of 2008-01-14 13:02:04
Size: 7659
Editor: abuehl
Comment: split out from FAQ
Revision 34 as of 2009-09-22 11:41:31
Size: 13181
Editor: PaulBoddie
Comment: Added an apparently relatively common question/issue. Feel free to edit, revert.
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
=== What can i configure in Mercurial === === Which revision have I checked out? ===
Use the [[Parent|parent]] command (TutorialClone shows an example call).

=== What can I configure in Mercurial ===
Line 4: Line 7:
=== Configuring the username ===
If hg says '''No username found, using 'user@hostname instead'''' when you make a commit, then you need to configure your username. Please see QuickStart for help on this.
Line 5: Line 11:
If your remote repository is cloned thusly
Line 6: Line 13:
If your remote repository is cloned thusly
Line 10: Line 16:
And, you find that after successful ssh authentication you get the error message '''remote: abort: repository path/to/repo not found!''' , then you need to know the following:
Line 11: Line 18:
And, you find that after successful ssh authentication you get the error message '''remote: abort: repository path/to/repo not found!''' , then you need to know the following:
 * Mercurial's remote repository
syntax differs from syntax of other well known programs such as rsync, cvs - both of which use a `:` character to delimit {{{USER@REMOTE}}} from the path component ({{{/path/to/repo}}}).
 * Mercurial's remote [[Repository|repository]] syntax differs from syntax of other well known programs such as rsync, cvs - both of which use a `:` character to delimit {{{USER@REMOTE}}} from the path component ({{{/path/to/repo}}}).
Line 16: Line 22:
On the other hand, if the error message is '''remote: bash: line 1: hg: command not found''', the problem is that the environment used by ssh does not have `hg` in its `PATH`. There are two ways to deal with this problem:

 * In your `~/.hgrc` file, set a `remotecmd` value in the `[ui]` section giving the exact path to `hg`.
 * On the server, create a `~/.ssh/environment` file that defines an appropriate `PATH`, and add `PermitUserEnvironment yes` to `/etc/sshd_config`.
Line 17: Line 28:

If you're on a network you trust you can add 
If you're on a network you trust you can add
Line 24: Line 34:
Line 30: Line 39:
There are two parts to Mercurial: the [[Repository|repository]] and the [[WorkingDirectory|working directory]]. {{{hg pull}}} [[Pull|pulls]] all new changes from a remote repository into the local one but doesn't alter the working directory.
Line 31: Line 41:
There are two parts to Mercurial: the repository and the working
directory. {{{hg pull}}} pulls all new changes from a remote repository
into the local one but doesn't alter the working directory.
This keeps you from upsetting your work in progress, which may not be ready to merge with the new changes you've pulled and also allows you to manage [[Merge|merging]] more easily (see below about best practices).
Line 35: Line 43:
This keeps you from upsetting your work in progress, which may not be
ready to merge with the new changes you've pulled and also allows you
to manage merging more easily (see below about best practices).

To update your working directory, run {{{hg update}}}. If you're sure you
want to update
your working directory on a pull, you can also use
{{{hg pull -u}}}. This will refuse to merge or overwrite local changes.
To update your working directory, run {{{hg update}}}. If you're sure you want to [[Update|update]] your working directory on a pull, you can also use {{{hg pull -u}}}. This will refuse to merge or overwrite local changes.
Line 44: Line 46:
Line 50: Line 51:

{{{hg status}}} reports when file '''contents''' or '''flags''' have changed relative to '''either''' parent. {{{hg diff}}} only reports changed '''contents''' relative to the first parent. You can see flag information with the {{{--git}}} option to {{{hg diff}}} and deltas relative to the other parent with {{{-r}}}. 
{{{hg status}}} reports when file '''contents''' or '''flags''' have changed relative to '''either''' [[Parent|parent]]. {{{hg diff}}} only reports changed '''contents''' relative to the first parent. You can see flag information with the {{{--git}}} option to {{{hg diff}}} and deltas relative to the other parent with {{{-r}}}.
Line 54: Line 54:
The [[Diff|diff]] shown by {{{hg diff}}}, {{{hg export}}} and {{{hg log}}} is always against the first [[Parent|parent]] for consistency. Also, the files listed are only the files that have changed relative to ''both'' parents.
Line 55: Line 56:
The diff shown by {{{hg export}}} and {{{hg log}}} is always against the first parent for consistency. Also, the files listed are only the files that have changed relative to ''both'' parents. (Are diffs of merges really always against the first parent? Doesn't {{{hg export}}} have a --switch-parent option? It would also be good if the docs would give the rational for {{{hg diff}}} and {{{hg log}}} not having that option (assuming they don't--the man page only mentions it for export).)
Line 58: Line 59:
You've probably done an {{{hg merge}}} (see [[Merge]]), which means your [[WorkingDirectory|working directory]] now has two [[Parent|parents]] according to {{{hg parents}}}. A subsequent {{{hg revert --all -r .}}} will revert all files in the working directory ''back to the first (primary) parent'', but it will still leave you with two parents (see [[Revert]]).
Line 59: Line 61:
You've probably done an {{{hg merge}}}, which means your working directory now has two parents according to {{{hg parents}}}. A subsequent {{{hg revert}}} will revert your working directory ''back to the primary parent'', thus leaving you with the differences between the two parents. {{{hg update -C}}} will revert the left files. To completely undo the uncommitted merge and discard all [[LocalModifications|local modifications]], you will need to issue a `hg update -C -r .` (note the "dot" at the end of the command).
Line 61: Line 63:
If you're trying to switch between revisions in history, you probably want
{{{hg update -C}}}.
See also TutorialMerge.
Line 65: Line 66:
The easiest thing to do is run {{{hg clone -U}}} which will create a fresh [[Clone|clone]] without checking out a working copy.
Line 66: Line 68:
The easiest thing to do is run {{{hg clone -U}}} which will create a fresh clone
without checking out a working copy.
If the repository already has a working copy, you can remove it running {{{hg update null}}}.
Line 69: Line 70:
'''Note''': you might want to copy hgrc file from your old repository. '''Note''': you might want to copy hgrc file from your old [[Repository|repository]].
Line 72: Line 73:

If you've just committed it, and you haven't done any other commits or pulls since, you may be able to use {{{rollback}}} to undo the last commit transaction:
If you've just [[Commit|committed]] it, and you haven't done any other commits or [[Pull|pulls]] since, you may be able to use {{{rollback}}} (see [[Rollback]]) to undo the last commit transaction:
Line 79: Line 79:
Line 85: Line 84:

The strip command in the mq extension may also be useful here for doing operations in place.
The strip command in the [[MqExtension|mq extension]] may also be useful here for doing operations in place.
Line 90: Line 88:
If you've already pushed your changes to a public repository that people have cloned from, the genie is out of the bottle. Good luck cleaning up your mess. If you've already pushed your changes to a public [[Repository|repository]] that people have [[Clone|cloned]] from, the genie is out of the bottle. Good luck cleaning up your mess.
Line 94: Line 92:
For more details, see EditingHistory.

=== I committed a large binary file/files how do I delete them permanently? ===
If you want to remove file(s) that shouldn't have been added, use the ConvertExtension with {{{--filemap}}} option to "convert" your Mercurial repository to another Mercurial repository. You'll want to make sure that you set {{{convert.hg.saverev=False}}} if you want to keep in common the history prior to your removed file(s). If {{{convert.hg.saverev=True}}}, the conversion embeds the source revision IDs into the new revisions under an {{{extra}}} header, visible if via {{{hg log --debug}}}.

See also the previous question for other options.
Line 95: Line 100:
Line 98: Line 102:
 * add a file, like "this-dir-intentionally-left-blank"  * add a file, like "this-dir-intentionally-left-blank" (there is also a tool MarkEmptyDirs which allows to automate this task).
Line 102: Line 106:
Use the NotifyExtension
Line 103: Line 108:
See CommitHook for an example. === I'd like to put only some few files of a large directory tree (home dir for instance) under Mercurial's control, and it is taking forever to diff or commit ===
Just do a
Line 105: Line 111:
=== I'd like to put only some few files of a large directory tree (home dir for instance) under mercurial's control, and it is taking forever to diff or commit ===

Just do a {{{
{{{
Line 110: Line 114:
or, if you are using 0.7 or below, {{{ or, if you are using 0.7 or below,

{{{
Line 113: Line 119:

This will make hg ignore all files except those explicitly added.
This will make [[.hgignore|hg ignore]] all files except those explicitly added.
Line 117: Line 122:
If you use automatic build tools like make or distutils, some built files might not be updated if you checkout an older revision of a file. Additionally a newer [[ChangeSet|changeset]] might have an older [[Commit|commit]] timestamp due to [[Pull|pulling]] from someone else or importing [[Patch|patches]] somebody has done some time ago, so checking out a ''newer'' changeset would have to make the files ''older'' in this case.
Line 118: Line 124:
If you use automatic build tools like make or distutils, some built files
might not be updated if you checkout an older revision of a file.
Additionally a newer changeset might have an older commit timestamp due to
pulling from someone else or importing patches somebody has done some time
ago, so checking out a ''newer'' changeset would have to make the files
''older'' in this case.

If you need predictable timestamps you can use ''hg archive'', which can do
something like a checkout in a separate directory. Because this directory is
newly created, there is nothing like switching to a different changeset
afterwards, therefore the above mentioned problems don't apply here.

=== My merge program failed, and now I don't know what to do ===

If your merge program fails you'll find yourself in a state where both hg up
and hg merge produce the same, unhelpful output.

{{{
abort: outstanding uncommitted merges
}}}

When this first happened, mercurial told you what to do, but if you've lost
those instructions, how does one recover them?

Why does hg merge not invoke merge again? Why the unhelpful output?
If you need predictable timestamps you can use ''hg archive'', which can do something like a checkout in a separate directory. Because this directory is newly created, there is nothing like switching to a different changeset afterwards, therefore the above mentioned problems don't apply here.
Line 149: Line 131:
This goes in .hg/hgrc on the remote [[Repository|repository]]. Output has to be redirected to stderr (or /dev/null), because stdout is used for the data stream.
Line 150: Line 133:
This goes in .hg/hgrc on the remote repository.
Output has to be redirected to stderr (or /dev/null), because stdout is used
for the data stream.

=== How can store my HTTP login once and for all ? ===
=== How can I store my HTTP login once and for all ? ===
Line 161: Line 139:
Then add a new entry in the ''paths'' section of your hgrc file. With Mercurial 1.3 you can also add an ''auth'' section to your hgrc file:
Line 162: Line 141:
Then add a new entry in the ''paths'' section of your hgrc file. {{{
[auth]
example.prefix = https://hg.example.net/
example.username = foo
example.password = bar
}}}
Please see [[http://www.selenic.com/mercurial/hgrc.5.html#auth|the hgrc manpage]] for more information.

=== How can I do a "hg log" of a remote repository? ===
You can't. Mercurial accepts only local [[Repository|repositories]] for the -R option (see {{{hg help -v log}}}).

{{{
> hg log -R http://www.selenic.com/repo/hello
abort: repository 'http://www.selenic.com/repo/hello' is not local
}}}
The correct way to do this is [[Clone|cloning]] the remote repository to your computer and then doing a {{{hg log}}} locally.

This is a very deliberate explicit design decision made by project leader Matt Mackall (mpm). See also http://www.selenic.com/mercurial/bts/issue1025 for the reasoning behind that.

=== How can I find out if there are new changesets in a remote repository? ===
To get the [[ChangeSetID|changeset id]] of the [[Tip|tipmost]] [[ChangeSet|changeset]] of a remote [[Repository|repository]] you can do:

{{{
> hg id -i -r tip http://www.selenic.com/repo/hello
82e55d328c8c
}}}
When it changes, you have new changesets in the remote repository.

=== What can I do with a head I don't want anymore? ===
See PruningDeadBranches

=== The clone command is returning the wrong version in my workspace! ===
[[Clone]] checks out the tip of the default (aka unnamed) branch (see NamedBranches). Ergo, you probably want to keep your main branch unnamed.

=== Any way to track ownership and permissions? ===
If you're using Mercurial for config file management, you might want to track file properties (ownership and permissions) too. Mercurial only tracks the executable bit of each file.

Here is an example of how to save the properties along with the files (works on Linux if you've the ''acl'' package installed):

{{{
# cd /etc && getfacl -R . >/tmp/acl.$$ && mv /tmp/acl.$$ .acl
# hg commit
}}}
This is far from perfect, but you get the idea. For a more sophisticated solution, check out ''etckeeper''.

=== I get a "no space left" or "disk quota exceeded" on push ===
I get a "no space left" or "disk quota exceeded" on push, but there is plenty of space or/and I have no quota limit on the device where the remote hg repository is.

The problem comes probably from the fact that mercurial uses {{{/tmp}}} (or one of the directory define by environment variables {{{$TMPDIR, $TEMP}}} or {{{$TMP}}}) to uncompress the bundle received on the wire. The decompression may then reach device limits.

You can of course set {{{$TMPDIR}}} to another location on remote in the default shell configuration file, but it will be potentially used by other processes than mercurial. Another solution is to set a hook in a global [[hgrc|.hgrc]] on remote. See the description of how to set a [[Hook#tmpdirhook|hook for changing tmp directory]] on remote when pushing.

=== Why do I get "abort: could not import module mpatch!" when invoking hg? ===
If your current directory is that of the Mercurial source distribution, it is possible that `hg` is looking in the local `mercurial` package directory and fails to find the `mpatch.so` extension module. The solution (for most situations) is to move out of the source distribution directory and to try again. (This is a common Python pitfall: Python will often be confused by packages or modules in the current directory and will import packages/modules from these local locations instead of looking in the appropriate places.)

Which revision have I checked out?

Use the parent command (TutorialClone shows an example call).

What can I configure in Mercurial

See in MercurialIni.

Configuring the username

If hg says No username found, using 'user@hostname instead' when you make a commit, then you need to configure your username. Please see QuickStart for help on this.

I get an error while cloning a remote repository via ssh

If your remote repository is cloned thusly

  hg clone ssh://USER@REMOTE/path/to/repo

And, you find that after successful ssh authentication you get the error message remote: abort: repository path/to/repo not found! , then you need to know the following:

  • Mercurial's remote repository syntax differs from syntax of other well known programs such as rsync, cvs - both of which use a : character to delimit USER@REMOTE from the path component (/path/to/repo).

  • The path to the remote repository is relative to $HOME of USER. i.e., it is  ~USER/path/to/repo .

  • Remember to use hg -v clone ssh://USER@REMOTE/path/to/repo and observe the remote command being executed via the ssh channel

On the other hand, if the error message is remote: bash: line 1: hg: command not found, the problem is that the environment used by ssh does not have hg in its PATH. There are two ways to deal with this problem:

  • In your ~/.hgrc file, set a remotecmd value in the [ui] section giving the exact path to hg.

  • On the server, create a ~/.ssh/environment file that defines an appropriate PATH, and add PermitUserEnvironment yes to /etc/sshd_config.

I get an "ssl required" error message when trying to push changes

If you're on a network you trust you can add

[web]
push_ssl = false

in your <repository-name>/.hg/hgrc file. (Taken from HgWebDirStepByStep)

There's a reason for requiring SSL, however. If you do not trust the network you are using do not change this.

I did an hg pull and my working directory is empty!

There are two parts to Mercurial: the repository and the working directory. hg pull pulls all new changes from a remote repository into the local one but doesn't alter the working directory.

This keeps you from upsetting your work in progress, which may not be ready to merge with the new changes you've pulled and also allows you to manage merging more easily (see below about best practices).

To update your working directory, run hg update. If you're sure you want to update your working directory on a pull, you can also use hg pull -u. This will refuse to merge or overwrite local changes.

I want to retrieve an old version of my project, what do I do?

You want hg update -C <version>, which will clobber your current version with the requested version.

You don't want hg revert <version>, which reverts changes in your working directory back to that version, but keeps the current parents for the next checkin. This command exists for undoing changes in current versions, not for working on old versions.

hg status shows changed files but hg diff doesn't!

hg status reports when file contents or flags have changed relative to either parent. hg diff only reports changed contents relative to the first parent. You can see flag information with the --git option to hg diff and deltas relative to the other parent with -r.

hg export or log -p shows a strange diff for my merge!

The diff shown by hg diff, hg export and hg log is always against the first parent for consistency. Also, the files listed are only the files that have changed relative to both parents.

(Are diffs of merges really always against the first parent? Doesn't hg export have a --switch-parent option? It would also be good if the docs would give the rational for hg diff and hg log not having that option (assuming they don't--the man page only mentions it for export).)

I did an hg revert and my working directory still has changes in it!

You've probably done an hg merge (see Merge), which means your working directory now has two parents according to hg parents. A subsequent hg revert --all -r . will revert all files in the working directory back to the first (primary) parent, but it will still leave you with two parents (see Revert).

To completely undo the uncommitted merge and discard all local modifications, you will need to issue a hg update -C -r . (note the "dot" at the end of the command).

See also TutorialMerge.

I want a clean, empty working directory

The easiest thing to do is run hg clone -U which will create a fresh clone without checking out a working copy.

If the repository already has a working copy, you can remove it running hg update null.

Note: you might want to copy hgrc file from your old repository.

I committed a change containing nuclear launch codes, how do I delete it permanently?

If you've just committed it, and you haven't done any other commits or pulls since, you may be able to use rollback (see Rollback) to undo the last commit transaction:

$ hg rollback
rolling back last transaction

If you've made other changes but you haven't yet published it to the world, you can do something like the following:

$ hg clone -r <untainted-revision> tainted-repo untainted-repo

The strip command in the mq extension may also be useful here for doing operations in place.

This will get you a new repo without the tainted change or the ones that follow it. You can import the further changes with hg export and hg import or by using the TransplantExtension. See TrimmingHistory for possible future approaches.

If you've already pushed your changes to a public repository that people have cloned from, the genie is out of the bottle. Good luck cleaning up your mess.

“Judge Tries to Unring Bell Hanging Around Neck of Horse Already Out of Barn Being Carried on Ship That Has Sailed.” - William G. Childs

For more details, see EditingHistory.

I committed a large binary file/files how do I delete them permanently?

If you want to remove file(s) that shouldn't have been added, use the ConvertExtension with --filemap option to "convert" your Mercurial repository to another Mercurial repository. You'll want to make sure that you set convert.hg.saverev=False if you want to keep in common the history prior to your removed file(s). If convert.hg.saverev=True, the conversion embeds the source revision IDs into the new revisions under an extra header, visible if via hg log --debug.

See also the previous question for other options.

I tried to check in an empty directory and it failed!

Mercurial doesn't track directories, it only tracks files. Which works for just about everything, except directories with no files in them. As empty directories aren't terribly useful and it makes the system much simpler, we don't intend to fix this any time soon. A couple workarounds:

  • add a file, like "this-dir-intentionally-left-blank" (there is also a tool MarkEmptyDirs which allows to automate this task).

  • create the directory with your Makefiles or other build processes

I want to get an email when a commit happens!

Use the NotifyExtension

I'd like to put only some few files of a large directory tree (home dir for instance) under Mercurial's control, and it is taking forever to diff or commit

Just do a

printf "syntax: glob\n*\n" > .hgignore

or, if you are using 0.7 or below,

printf ".*\n" > .hgignore

This will make hg ignore all files except those explicitly added.

Why is the modification time of files not restored on checkout?

If you use automatic build tools like make or distutils, some built files might not be updated if you checkout an older revision of a file. Additionally a newer changeset might have an older commit timestamp due to pulling from someone else or importing patches somebody has done some time ago, so checking out a newer changeset would have to make the files older in this case.

If you need predictable timestamps you can use hg archive, which can do something like a checkout in a separate directory. Because this directory is newly created, there is nothing like switching to a different changeset afterwards, therefore the above mentioned problems don't apply here.

Any way to 'hg push' and have an automatic 'hg update' on the remote server?

[hooks]
changegroup = hg update >&2

This goes in .hg/hgrc on the remote repository. Output has to be redirected to stderr (or /dev/null), because stdout is used for the data stream.

How can I store my HTTP login once and for all ?

You can specify the usename and password in the URL like:

http://user:password@mydomain.org

Then add a new entry in the paths section of your hgrc file. With Mercurial 1.3 you can also add an auth section to your hgrc file:

[auth]
example.prefix = https://hg.example.net/
example.username = foo
example.password = bar

Please see the hgrc manpage for more information.

How can I do a "hg log" of a remote repository?

You can't. Mercurial accepts only local repositories for the -R option (see hg help -v log).

> hg log -R http://www.selenic.com/repo/hello
abort: repository 'http://www.selenic.com/repo/hello' is not local

The correct way to do this is cloning the remote repository to your computer and then doing a hg log locally.

This is a very deliberate explicit design decision made by project leader Matt Mackall (mpm). See also http://www.selenic.com/mercurial/bts/issue1025 for the reasoning behind that.

How can I find out if there are new changesets in a remote repository?

To get the changeset id of the tipmost changeset of a remote repository you can do:

> hg id -i -r tip http://www.selenic.com/repo/hello
82e55d328c8c

When it changes, you have new changesets in the remote repository.

What can I do with a head I don't want anymore?

See PruningDeadBranches

The clone command is returning the wrong version in my workspace!

Clone checks out the tip of the default (aka unnamed) branch (see NamedBranches). Ergo, you probably want to keep your main branch unnamed.

Any way to track ownership and permissions?

If you're using Mercurial for config file management, you might want to track file properties (ownership and permissions) too. Mercurial only tracks the executable bit of each file.

Here is an example of how to save the properties along with the files (works on Linux if you've the acl package installed):

# cd /etc && getfacl -R . >/tmp/acl.$$ && mv /tmp/acl.$$ .acl
# hg commit

This is far from perfect, but you get the idea. For a more sophisticated solution, check out etckeeper.

I get a "no space left" or "disk quota exceeded" on push

I get a "no space left" or "disk quota exceeded" on push, but there is plenty of space or/and I have no quota limit on the device where the remote hg repository is.

The problem comes probably from the fact that mercurial uses /tmp (or one of the directory define by environment variables $TMPDIR, $TEMP or $TMP) to uncompress the bundle received on the wire. The decompression may then reach device limits.

You can of course set $TMPDIR to another location on remote in the default shell configuration file, but it will be potentially used by other processes than mercurial. Another solution is to set a hook in a global .hgrc on remote. See the description of how to set a hook for changing tmp directory on remote when pushing.

Why do I get "abort: could not import module mpatch!" when invoking hg?

If your current directory is that of the Mercurial source distribution, it is possible that hg is looking in the local mercurial package directory and fails to find the mpatch.so extension module. The solution (for most situations) is to move out of the source distribution directory and to try again. (This is a common Python pitfall: Python will often be confused by packages or modules in the current directory and will import packages/modules from these local locations instead of looking in the appropriate places.)

FAQ/CommonProblems (last edited 2018-02-22 02:01:15 by JohnHein)