# HG changeset patch # User mpm@selenic.com # Date 1124264993 28800 # Node ID fdf3b7f3b3b42dcd669220dcc091b99bf9b7cefc # Parent 32e8f64b25b0d7c0ee5821cdad3b66634c52f244 The TODO and the FAQ now live on the Wiki diff -r 32e8f64b25b0 -r fdf3b7f3b3b4 TODO --- 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 should work (currently only: hg add -I ) -- hg status : 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 diff -r 32e8f64b25b0 -r fdf3b7f3b3b4 doc/FAQ.txt --- 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 ? - -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). - - -