Differences between revisions 10 and 24 (spanning 14 versions)
Revision 10 as of 2008-01-13 20:58:52
Size: 2761
Editor: abuehl
Comment:
Revision 24 as of 2012-11-06 16:23:25
Size: 3326
Editor: abuehl
Comment: fix links
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Working directory == #pragma section-numbers 2
= Working directory =
The '''working directory''' is the top-level directory in a [[Repository|repository]], in which the plain versions of files are available to read, edit and build. Files in the working directory are usually from the [[Tip|tip]], but may be from older [[Revision|revisions]], or modified and not yet committed. The working directory is sometimes called the "working copy."
Line 3: Line 5:
The '''working directory''' is the top-level directory in a [:Repository:repository], in which the plain versions of files are available to read, edit and build. Files in the working directory are usually from the [:Tip:tip], but may be from older [:Revision:revisions], or modified and not yet [:Commit:committed]. <<TableOfContents>>
Line 5: Line 7:
A working directory has one or two [:Parent:parent] revisions. The parent revision or revisions will become the parent revisions of the new revision which will eventually be created by a commit of the [:LocalModifications:local modifications]. An [:Update:update] will change the parent revision, whereas a [:Revert:revert] will only modify the content of the working directory. == Manipulating the Working Directory ==
Line 7: Line 9:
A working directory will only have two parent revisions as the result of a [:Merge:merge]. It’s useful to think of the working directory as "the changeset I’m about to commit". If the working directory has no [[LocalModifications|local modifications]] it is said to be ''clean''.
Line 9: Line 11:
A [:NamedBranches:branch name] can be set for the working directory. Use {{{hg revert}}} to discard all local modifications (see [[Cmd:revert]]).
Line 11: Line 13:
It’s useful to think of the working directory as "the [:ChangeSet:changeset] I’m about to commit". Use {{{hg update}}} to bring the working directory into sync with a particular [[ChangeSet|changeset]] (see [[Cmd:update]]).
Line 13: Line 15:

=== Tracking Working Directory State ===

Mercurial tracks various information about the working directory (the '''dirstate'''):

 * what revision(s) are currently checked out
 * what files have been copied or renamed
 * what files are controlled by Mercurial

For each file that Mercurial controls, we record the following information:

 * its size
 * its mode
 * its modification time
 * its "state"

The states that are tracked are:

 * n - normal
 * a - added
 * r - removed
 * m - 3-way merged

With this information, we can quickly determine what files in the working directory have changed.

Here's an example of the dirstate:
To remove all files from the working directory (not the repository!), you can do
Line 41: Line 18:
$ hg parents -q
1224:cc61d366bc3b
$ hg debugstate
n 644 168 08/19/05 17:42:17 .hgignore
n 644 412 08/20/05 01:46:57 .hgtags
n 644 1328 08/26/05 23:22:20 CONTRIBUTORS
n 644 17992 06/30/05 10:19:51 COPYING
n 644 459 08/24/05 00:38:20 MANIFEST.in
n 644 512 08/24/05 00:35:02 Makefile
n 644 232 06/30/05 10:19:51 PKG-INFO
n 644 2736 08/20/05 00:48:33 README
n 644 1676 06/30/05 10:19:51 comparison.txt
n 644 3711 12/31/69 15:59:59 contrib/bash_completion
n 711 1305 07/01/05 15:04:52 contrib/buildrpm
n 755 8300 08/16/05 16:03:59 contrib/convert-repo
n 644 69 06/30/05 10:19:51 contrib/git-viz/git-cat-file
n 644 69 06/30/05 10:19:51 contrib/git-viz/git-diff-tree
n 644 69 06/30/05 10:19:51 contrib/git-viz/git-rev-list
n 644 69 06/30/05 10:19:51 contrib/git-viz/git-rev-tree
n 644 457 06/30/05 10:19:51 contrib/git-viz/hg-viz
n 755 8039 08/16/05 16:03:59 contrib/hgit
n 755 40043 06/30/05 10:19:51 contrib/hgk
...
hg update null
Line 65: Line 20:
A [[NamedBranches|branch name]] can be set for the working directory.

Mercurial tracks various information about the working directory (see DirState).

== Parent(s) ==
A working directory has one or two parent revisions. The parent revision (or revisions) will become the parent revisions of the new revision which will eventually be created by a commit of the local modifications.

An {{{hg update}}} will change the parent revision, whereas {{{hg revert}}} will only modify the content of the working directory.

A working directory will only have two parent revisions as the result of a [[Merge|merge]], but only until that merge has been committed.

Immediately after a commit (or after an update -C), the working directory has exactly ''one'' parent revision, namely the newly committed (or updated-to) changeset. This is even the case if the newly committed changeset was a merge.

The command {{{hg parents}}} (without a revision specifier) lists the parent revision(s) of the working directory.

Example output for a single parent (no uncommitted merge):

{{{
$ hg parents
changeset: 2:86794f718fb1
tag: tip
user: mpm@selenic.com
date: Mon May 05 01:20:46 2008 +0200
summary: Express great joy at existence of Mercurial
}}}
Example output for two parent revisions (after an uncommitted merge):

{{{
$ hg parents
changeset: 2:c3844fde99f0
user: mpm@selenic.com
date: Tue May 06 20:10:35 2008 +0200
summary: Add description of hello.c

changeset: 3:86794f718fb1
tag: tip
parent: 1:82e55d328c8c
user: mpm@selenic.com
date: Mon May 05 01:20:46 2008 +0200
summary: Express great joy at existence of Mercurial
}}}
== When an update is needed ==
There are several ways to see if an update of your working directory is needed (see related [[http://www.selenic.com/pipermail/mercurial/2006-September/010951.html|mailing list thread]]):

To see the delta between the working directory and the tip, do:

{{{
hg diff -r tip
}}}
To see what patches would be applied to the working directory on an update do:

{{{
hg log -r tip:.
}}}
If the working directory is at the tip (that is, no update needed)

{{{
hg id
}}}
will write "tip" after the changeset id.

Working directory

The working directory is the top-level directory in a repository, in which the plain versions of files are available to read, edit and build. Files in the working directory are usually from the tip, but may be from older revisions, or modified and not yet committed. The working directory is sometimes called the "working copy."

1. Manipulating the Working Directory

It’s useful to think of the working directory as "the changeset I’m about to commit". If the working directory has no local modifications it is said to be clean.

Use hg revert to discard all local modifications (see revert).

Use hg update to bring the working directory into sync with a particular changeset (see update).

To remove all files from the working directory (not the repository!), you can do

hg update null

A branch name can be set for the working directory.

Mercurial tracks various information about the working directory (see DirState).

2. Parent(s)

A working directory has one or two parent revisions. The parent revision (or revisions) will become the parent revisions of the new revision which will eventually be created by a commit of the local modifications.

An hg update will change the parent revision, whereas hg revert will only modify the content of the working directory.

A working directory will only have two parent revisions as the result of a merge, but only until that merge has been committed.

Immediately after a commit (or after an update -C), the working directory has exactly one parent revision, namely the newly committed (or updated-to) changeset. This is even the case if the newly committed changeset was a merge.

The command hg parents (without a revision specifier) lists the parent revision(s) of the working directory.

Example output for a single parent (no uncommitted merge):

$ hg parents
changeset:   2:86794f718fb1
tag:         tip
user:        mpm@selenic.com
date:        Mon May 05 01:20:46 2008 +0200
summary:     Express great joy at existence of Mercurial

Example output for two parent revisions (after an uncommitted merge):

$ hg parents
changeset:   2:c3844fde99f0
user:        mpm@selenic.com
date:        Tue May 06 20:10:35 2008 +0200
summary:     Add description of hello.c

changeset:   3:86794f718fb1
tag:         tip
parent:      1:82e55d328c8c
user:        mpm@selenic.com
date:        Mon May 05 01:20:46 2008 +0200
summary:     Express great joy at existence of Mercurial

3. When an update is needed

There are several ways to see if an update of your working directory is needed (see related mailing list thread):

To see the delta between the working directory and the tip, do:

hg diff -r tip

To see what patches would be applied to the working directory on an update do:

hg log -r tip:.

If the working directory is at the tip (that is, no update needed)

hg id

will write "tip" after the changeset id.


CategoryGlossary

WorkingDirectory (last edited 2012-11-06 16:23:25 by abuehl)