Mercurial > hg

--- a/TODO	Tue Aug 16 22:47:49 2005 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,56 +0,0 @@
-General:
-- Better documentation
-- More regression tests
-- More specific try/except.
-- less code duplication, more code in the right places
-- python 2.2 support
-- export to git
-- Code cleanup: apply http://python.org/peps/pep-0008.html
-
-Core:
-- difflib creating/removing files (fixed except dates: should be epoch)
-- directory foo.d or foo.i with existing file foo (use some quoting?)
-- get various options from hgrc (e.g. history always -v, tip always -q)
-- hg over https:// and rsync://
-- hooks for new changesets getting pulled/imported etc.
-- make showing removed files (in history etc.) faster.
-- hgmerge error: merge should abort nicely and running it again should work
-- if hardlinking fails, pull should be used
-- .hgignore should use new patterns
-
-Commands:
-- hg add <directory> should work (currently only: hg add -I <dir>)
-- hg status <filename>: file rev, changeset rev, changed, added,
-  deleted, sha-1
-- select to pull a subset of the heads
-- commands.py: number of args too much magic (e.g. in import_())
-- optionally only show merges (two parents)
-- automatic pull fallback to old-http://
-- pass options to ssh (debug/verbose/remote hg command etc.)
-- create a commented .hg/hgrc on init/clone
-- hg pull default in a subdir doesn't work, if it is a relative path
-- hg clone should store corrected relative paths, so moving a directory
-  containing related repositories works again
-- if everyone knows 'hg clone': hg init [DIR]
-- if everyone knows 'hg update -m': remove -t
-- hg revert does not forget added files, it probably should.
-- hg pull should state if there are more heads than before.
-- hg clone: locking the repository while hardlinking.
-- hg clone: fall back to pull if hardlink not possible.
-- "hg diff not_existing" should yield an error message.
-
-Web:
-- optionally only show merges (two parents)
-- one hgweb with many repos (another script)
-- hgweb tip link too long (URL?cmd=changelog;rev=)
-- hgweb: shorter links (e.g. cs=... instead of cmd=changeset;node=...?)
-- hgweb: deliver static files (e.g. favicon, stylesheets)
-- hgweb personalization: timezone (display/change), display of
-  features, number of entries per page
-- some web servers think hgweb.cgi.[di] is a CGI script with old-http://
-  (use quoting (see foo.d in Core) or document server configurations?)
-- link children in hgweb
-- allow verbose mode
-- hide trivial parent (like in show_changeset)
-- default port for hg serve configurable in hgrc
-- download tarball via web interface
--- a/doc/FAQ.txt	Tue Aug 16 22:47:49 2005 -0800
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,317 +0,0 @@
-Mercurial Frequently Asked Questions
-====================================
-
-Section 1: General Usage
-------------------------
-
-.Q. 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.
-
-
-.Q. What are revision numbers, changeset IDs, and tags?
-
-Mercurial will generally allow you to refer to a revision in three
-ways: by revision number, by changeset ID, and by tag.
-
-A revision number is a simple decimal number that corresponds with the
-ordering of commits in the local repository. It is important to
-understand that this ordering can change from machine to machine due
-to Mercurial's distributed, decentralized architecture.
-
-This is where changeset IDs come in. A changeset ID is a 160-bit
-identifier that uniquely describes a changeset and its position in the
-change history, regardless of which machine it's on. This is
-represented to the user as a 40 digit hexadecimal number. As that
-tends to be unwieldy, Mercurial will accept any unambiguous substring
-of that number when specifying versions. It will also generally print
-these numbers in "short form", which is the first 12 digits.
-
-You should always use some form of changeset ID rather than the local
-revision number when discussing revisions with other Mercurial users
-as they may have different revision numbering on their system.
-
-Finally, a tag is an arbitrary string that has been assigned a
-correspondence to a changeset ID. This lets you refer to revisions
-symbolically.
-
-
-.Q. What are branches, heads, and the tip?
-
-The central concept of Mercurial is branching. A 'branch' is simply
-an independent line of development. In most other version control
-systems, all users generally commit to the same line of development
-called 'the trunk' or 'the main branch'. In Mercurial, every developer
-effectively works on a private branch and there is no internal concept
-of 'the main branch'.
-
-Thus Mercurial works hard to make repeated merging between branches
-easy. Simply run "hg pull" and "hg update -m" and commit the result.
-
-'Heads' are simply the most recent commits on a branch. Technically,
-they are changesets which have no children. Merging is the process of
-joining points on two branches into one, usually at their current
-heads. Use "hg heads" to find the heads in the current repository.
-
-The 'tip' is the most recently changed head, and also the highest
-numbered revision. If you have just made a commit, that commit will be
-the tip. Alternately, if you have just pulled from another
-repository, the tip of that repository becomes the current tip.
-
-The 'tip' is the default revision for many commands such as update,
-and also functions as a special symbolic tag.
-
-
-.Q. How does merging work?
-
-The merge process is simple. Usually you will want to merge the tip
-into your working directory. Thus you run "hg update -m" and Mercurial
-will incorporate the changes from tip into your local changes.
-
-The first step of this process is tracing back through the history of
-changesets and finding the 'common ancestor' of the two versions that
-are being merged. This is done on a project-wide and a file by file
-basis.
-
-For files that have been changed in both projects, a three-way merge
-is attempted to add the changes made remotely into the changes made
-locally. If there are conflicts between these changes, the user is
-prompted to interactively resolve them.
-
-Mercurial uses a helper tool for this, which is usually found by the
-hgmerge script. Example tools include tkdiff, kdiff3, and the classic
-RCS merge.
-
-After you've completed the merge and you're satisfied that the results
-are correct, it's a good idea to commit your changes. Mercurial won't
-allow you to perform another merge until you've done this commit as
-that would lose important history that will be needed for future
-merges.
-
-
-.Q. How do tags work in Mercurial?
-
-Tags work slightly differently in Mercurial than most revision
-systems. The design attempts to meet the following requirements:
-
-- be version controlled and mergeable just like any other file
-- allow signing of tags
-- allow adding a tag to an already committed changeset
-- allow changing tags in the future
-
-Thus Mercurial stores tags as a file in the working dir. This file is
-called .hgtags and consists of a list of changeset IDs and their
-corresponding tags. To add a tag to the system, simply add a line to
-this file and then commit it for it to take effect. The "hg tag"
-command will do this for you and "hg tags" will show the currently
-effective tags.
-
-Note that because tags refer to changeset IDs and the changeset ID is
-effectively the sum of all the contents of the repository for that
-change, it is impossible in Mercurial to simultaneously commit and add
-a tag. Thus tagging a revision must be done as a second step.
-
-
-.Q. What if I want to just keep local tags?
-
-You can use "hg tag" command with an option "-l" or "--local". This
-will store the tag in the file .hg/localtags, which will not be
-distributed or versioned. The format of this file is identical to the
-one of .hgtags and the tags stored there are handled the same.
-
-
-.Q. How do tags work with multiple heads?
-
-The tags that are in effect at any given time are the tags specified
-in each head, with heads closer to the tip taking precedence. Local
-tags override all other tags.
-
-
-.Q. What are some best practices for distributed development with Mercurial?
-
-First, merge often! This makes merging easier for everyone and you
-find out about conflicts (which are often rooted in incompatible
-design decisions) earlier.
-
-Second, don't hesitate to use multiple trees locally. Mercurial makes
-this fast and light-weight. Typical usage is to have an incoming tree,
-an outgoing tree, and a separate tree for each area being worked on.
-
-The incoming tree is best maintained as a pristine copy of the
-upstream repository. This works as a cache so that you don't have to
-pull multiple copies over the network. No need to check files out here
-as you won't be changing them.
-
-The outgoing tree contains all the changes you intend for merge into
-upsteam. Publish this tree with 'hg serve" or hgweb.cgi or use 'hg
-push" to push it to another publicly availabe repository.
-
-Then, for each feature you work on, create a new tree. Commit early
-and commit often, merge with incoming regularly, and once you're
-satisfied with your feature, pull the changes into your outgoing tree.
-
-
-.Q. How do I import from a repository created in a different SCM?
-
-Take a look at contrib/convert-repo. This is an extensible
-framework for converting between repository types.
-
-
-.Q. What about Windows support?
-
-Patches to support Windows are being actively integrated, a fully
-working Windows version is probably not far off
-
-
-Section 2: Bugs and Features
-----------------------------
-
-.Q. I found a bug, what do I do?
-
-Report it to the mercurial mailing list, mercurial@selenic.com.
-
-
-.Q. What should I include in my bug report?
-
-Enough information to reproduce or diagnose the bug. If you can, try
-using the hg -v and hg -d switches to figure out exactly what
-Mercurial is doing.
-
-If you can reproduce the bug in a simple repository, that is very
-helpful. The best is to create a simple shell script to automate this
-process, which can then be added to our test suite.
-
-
-.Q. Can Mercurial do <x>?
-
-If you'd like to request a feature, send your request to
-mercurial@selenic.com. As Mercurial is still very new, there are
-certainly features it is missing and you can give us feedback on how
-best to implement them.
-
-
-Section 3: Technical
---------------------
-
-.Q. What limits does Mercurial have?
-
-Mercurial currently assumes that single files, indices, and manifests
-can fit in memory for efficiency.
-
-Offsets in revlogs are currently tracked with 32 bits, so a revlog for
-a single file can currently not grow beyond 4G.
-
-There should otherwise be no limits on file name length, file size,
-file contents, number of files, or number of revisions.
-
-The network protocol is big-endian.
-
-File names cannot contain the null character. Committer addresses
-cannot contain newlines.
-
-Mercurial is primarily developed for UNIX systems, so some UNIXisms
-may be present in ports.
-
-
-.Q. How does Mercurial store its data?
-
-The fundamental storage type in Mercurial is a "revlog". A revlog is
-the set of all revisions of a named object. Each revision is either
-stored compressed in its entirety or as a compressed binary delta
-against the previous version. The decision of when to store a full
-version is made based on how much data would be needed to reconstruct
-the file. This lets us ensure that we never need to read huge amounts
-of data to reconstruct a object, regardless of how many revisions of it
-we store.
-
-In fact, we should always be able to do it with a single read,
-provided we know when and where to read. This is where the index comes
-in. Each revlog has an index containing a special hash (nodeid) of the
-text, hashes for its parents, and where and how much of the revlog
-data we need to read to reconstruct it. Thus, with one read of the
-index and one read of the data, we can reconstruct any version in time
-proportional to the object size.
-
-Similarly, revlogs and their indices are append-only. This means that
-adding a new version is also O(1) seeks.
-
-Revlogs are used to represent all revisions of files, manifests, and
-changesets. Compression for typical objects with lots of revisions can
-range from 100 to 1 for things like project makefiles to over 2000 to
-1 for objects like the manifest.
-
-
-.Q. How are manifests and changesets stored?
-
-A manifest is simply a list of all files in a given revision of a
-project along with the nodeids of the corresponding file revisions. So
-grabbing a given version of the project means simply looking up its
-manifest and reconstructing all the file revisions pointed to by it.
-
-A changeset is a list of all files changed in a check-in along with a
-change description and some metadata like user and date. It also
-contains a nodeid to the relevent revision of the manifest.
-
-
-.Q. How do Mercurial hashes get calculated?
-
-Mercurial hashes both the contents of an object and the hash of its
-parents to create an identifier that uniquely identifies an object's
-contents and history. This greatly simplifies merging of histories
-because it avoid graph cycles that can occur when a object is reverted
-to an earlier state.
-
-All file revisions have an associated hash value. These are listed in
-the manifest of a given project revision, and the manifest hash is
-listed in the changeset. The changeset hash is again a hash of the
-changeset contents and its parents, so it uniquely identifies the
-entire history of the project to that point.
-
-
-.Q. What checks are there on repository integrity?
-
-Every time a revlog object is retrieved, it is checked against its
-hash for integrity. It is also incidentally doublechecked by the
-Adler32 checksum used by the underlying zlib compression.
-
-Running 'hg verify' decompresses and reconstitutes each revision of
-each object in the repository and cross-checks all of the index
-metadata with those contents.
-
-But this alone is not enough to ensure that someone hasn't tampered
-with a repository. For that, you need cryptographic signing.
-
-
-.Q. How does signing work with Mercurial?
-
-Take a look at the hgeditor script for an example. The basic idea is
-to use GPG to sign the manifest ID inside that changelog entry. The
-manifest ID is a recursive hash of all of the files in the system and
-their complete history, and thus signing the manifest hash signs the
-entire project contents.
-
-
-.Q. What about hash collisions? What about weaknesses in SHA1?
-
-The SHA1 hashes are large enough that the odds of accidental hash collision
-are negligible for projects that could be handled by the human race.
-The known weaknesses in SHA1 are currently still not practical to
-attack, and Mercurial will switch to SHA256 hashing before that
-becomes a realistic concern.
-
-Collisions with the "short hashes" are not a concern as they're always
-checked for ambiguity and are still long enough that they're not
-likely to happen for reasonably-sized projects (< 1M changes).
-
-
-