# # # add_dir "wiki/BuildingOnWindows" # # add_dir "wiki/DeltaStorageStrategies" # # add_dir "wiki/MtnSummit" # # add_dir "wiki/MtnSummit2008" # # add_dir "wiki/PerformanceWork" # # add_dir "wiki/RostersTodo" # # add_dir "wiki/SummerOfCode2007" # # add_dir "wiki/TestHarnessIssues" # # add_dir "wiki/VersionedPolicy" # # add_file "wiki/AlternativeOverview.moin" # content [0029709cf3c3ad22cb68c8f3c6473a3be5e07790] # # add_file "wiki/AttrUseCases.moin" # content [2d4a515f1570b9b0742bc0405a481340175fba3f] # # add_file "wiki/AutoInodeprints.moin" # content [e08af3462cb1553add68a59e456e6ba9c3778b88] # # add_file "wiki/AutomateMagic.moin" # content [2724845adddeba413546d3b0de606e72b4edfe46] # # add_file "wiki/AutomateVersions.moin" # content [8fe4aed794a15346037232c734d1b406017aa7d6] # # add_file "wiki/AutomateWishlist.moin" # content [f3bb3bdae39ddb18e4ede0eeaeddb6cea8abdb84] # # add_file "wiki/BasicIoFormalization.moin" # content [c0f2b9a879db4c1cb480a5cc71e2d75bd02c447c] # # add_file "wiki/BestPractices.moin" # content [9e4acb167835df9bbc9c7b3c6553c0b43407d6b9] # # add_file "wiki/BranchAnalogy.moin" # content [69abef4c1813f7a5818525da77e1d9fd086062e2] # # add_file "wiki/BranchNamingConventions.moin" # content [ca8b98456a645a38e80fb0e3d262ae21f3c7a391] # # add_file "wiki/BranchRenaming.moin" # content [a0d5788f425f769f52ee6e2beb1ffa1fc6c965cd] # # add_file "wiki/BranchStatuses.moin" # content [812a0cacf85649e9048dd5565cc999419caeba14] # # add_file "wiki/BranchUI.moin" # content [5897ef1838f3d13d94953899703b12e59a1c225e] # # add_file "wiki/BugSquashingParty.moin" # content [2e9e6b95e37d59ece66e2e74822907d7717a2d2a] # # add_file "wiki/BuildBot.moin" # content [7c24a658a87cec3360d3091a91c5a834a9cbbb3f] # # add_file "wiki/BuildBotWindows.moin" # content [deca46ad5b6288e334148a6940c4c3ca574a6fbb] # # add_file "wiki/BuildingOnMac.moin" # content [8e18c22e92eb6a0b0d2bad3a4ea7065821787771] # # add_file "wiki/BuildingOnSolaris.moin" # content [a3534a897e8126fde927e9c9966da24a9a3bf574] # # add_file "wiki/BuildingOnWindows/FVC8.moin" # content [cc2cfccb331742343b64e1836ef6dbd3d1436139] # # add_file "wiki/BuildingOnWindows/FVisualC8.moin" # content [d598f53c08ce10e7405e13f34a375decb133f778] # # add_file "wiki/BuildingOnWindows.moin" # content [7d4c4fde88cc5f8d1fd2b061be594734a33f6999] # # add_file "wiki/BuildingViaPkgsrc.moin" # content [3b33859830e445df2fc2095c4b7ae2affa06f134] # # add_file "wiki/CarrotAndStick.moin" # content [cdde4c203d05d2a72f52e4e3b86a5991436cd507] # # add_file "wiki/CaseInsensitiveFilesystems.moin" # content [ed3bdd8d05b0625558c8a29e0d72abac456fc17a] # # add_file "wiki/CertCleanup.moin" # content [c47fd639b8465493a96065fe6dc36e12ea7086ef] # # add_file "wiki/ChadWalstrom.moin" # content [5ae7f609607231dd8a8429ebdafd94a11448e435] # # add_file "wiki/ChangeLog.moin" # content [7ae6cc3b924c08cbe32cd85f74aec76697ca6a29] # # add_file "wiki/CherryPicking.moin" # content [1d4f82bab5129c0293f8ceee7b6c18f0cfea9a16] # # add_file "wiki/ChristofPetig.moin" # content [307ebcf0bf77c77c1ab7fc4041ac9f44fd6ffe6e] # # add_file "wiki/CommitEarlyCommitOften.moin" # content [2a5ce9d87b63b604915bf2f6d8ed5cdaf364ff9a] # # add_file "wiki/ConflictFixupPolicy.moin" # content [9c7e2bb32e0c20487fbe416e70a99a73c4c2e77e] # # add_file "wiki/CraigLennox.moin" # content [b3b5cd92610b50b0c40a750654f5956964cf6363] # # add_file "wiki/CreatingBranches.moin" # content [4604514e5fbbbac792bed9166495397a6e819735] # # add_file "wiki/CustomCerts.moin" # content [12f373f28321765641cd2c11b16c7b898ee63271] # # add_file "wiki/CvsImport.moin" # content [3d5dcd92ea387b33e0a7746faf25937599da0a70] # # add_file "wiki/CvsSync.moin" # content [3bc2bc0b23d7a4d9d92bd1a5ed82bf3fbf9dab0f] # # add_file "wiki/CvsSync3.moin" # content [1328aa4f58d623e4d2e30e55d543ca7d4de8d980] # # add_file "wiki/CvsSyncHints.moin" # content [897868caa72b02a7a63e076a795b5301e7c64196] # # add_file "wiki/DagBasedRefinement.moin" # content [37da0c8d23a1a51c371a90c8e9482baf67c8edd7] # # add_file "wiki/DaggyFixes.moin" # content [58b4395f8be0f8ccee41f3c37b691082ea6df17f] # # add_file "wiki/DatabaseCompaction.moin" # content [9f155aac55327094cc95a4eabfa168705e47aefc] # # add_file "wiki/DatabaseLocking.moin" # content [10a3ab523a33216b9943e9113308a30bbbc364be] # # add_file "wiki/DeltaStorageStrategies/DeltaStorageStrategies%2FShootOut.moin" # content [dd0b0d51efc27bc72c6825e27875ef28f83428ad] # # add_file "wiki/DeltaStorageStrategies.moin" # content [bd9cbd626092970d68005364aff90008380ecac4] # # add_file "wiki/DerekScherger.moin" # content [f22501976e4e878a786edf6221944d2527a69234] # # add_file "wiki/DevGroup.moin" # content [3e26e8355833e3b04744c6b893e6c98dcee3edec] # # add_file "wiki/DifferentDbsForServeAndWork.moin" # content [2839715a5aee64481fe929af6def244514139fea] # # add_file "wiki/DocTodo.moin" # content [ea5b07eec1ba0b917ac4fbeb334a6f336230205e] # # add_file "wiki/EmileSnyder.moin" # content [2e482b3b818313e543baa791c73e927930004ba7] # # add_file "wiki/EssentialMonotone.moin" # content [f1ecd084a3c201cb3ff9fdc9208b24bf5b1c709a] # # add_file "wiki/EvaluationFeatures.moin" # content [1487779e18771c1e42562df66fa3522a188e5d1d] # # add_file "wiki/FAQ.moin" # content [ec9e4100d5748efeaf38465f096c03ab5fb73db6] # # add_file "wiki/FeatureAccessControl.moin" # content [8f7c9fe5d34752bad05c8c3007c49f0a8fc20fda] # # add_file "wiki/FeatureAtomicCommit.moin" # content [469132dcb1d0fb699a76631859bc0ea9e6ceb6ae] # # add_file "wiki/FeatureBuildIntegration.moin" # content [2dd9641c27e5a6c155f65eb2a07df3fda444f892] # # add_file "wiki/FeatureCVSExport.moin" # content [ef43adf7b60c45efe9bebafd0fd9cc69f4d58841] # # add_file "wiki/FeatureCVSImport.moin" # content [cab653a8e28ccc3be9552b893ead580eeb91a68b] # # add_file "wiki/FeatureCommitMail.moin" # content [fb5b17ceb5b3bf9a695dda9d061588219009da12] # # add_file "wiki/FeatureCompactRepository.moin" # content [a7eb23003f1e60e43667394887705a52fb89bc18] # # add_file "wiki/FeatureEmbeddedIDs.moin" # content [5e31f7b8fe2e8e5981fd37021776c4f3f7ce6589] # # add_file "wiki/FeatureFast.moin" # content [f1f75891942a3cb75dce7f4e56d86e505bc5be52] # # add_file "wiki/FeatureLightweightBranches.moin" # content [aad2b4d0e1090373a9a1ff2625a4ab051ca08f97] # # add_file "wiki/FeatureLogReview.moin" # content [af13f2028f5066c6c465554cd4aca95cebdfc685] # # add_file "wiki/FeatureLogTemplates.moin" # content [6b95d3adfff23d25a6dbae1febe95f054f80427b] # # add_file "wiki/FeatureMIMEtypes.moin" # content [cbefa97b30b877d7567618f7f1bc4b81ac464dee] # # add_file "wiki/FeatureMerging.moin" # content [8c6ec6653a5f36e274b737147a00ee451e454c69] # # add_file "wiki/FeatureMirroring.moin" # content [baf14ce474fc0b2a7e726b4a16b22c90836ec5fa] # # add_file "wiki/FeatureNetworkSecurity.moin" # content [a6108cdc69b1566413971c22fefd6ad070b722ae] # # add_file "wiki/FeatureObliterate.moin" # content [07da7a6da68dddc91f5a1be4c91699dfbaeb00f4] # # add_file "wiki/FeatureOffline.moin" # content [e1fbc090b60dd2e43fc9871ef70d7c230662445c] # # add_file "wiki/FeaturePortable.moin" # content [58dc1094939cdd44ebb9fedc8c5d9fbb04458399] # # add_file "wiki/FeatureRename.moin" # content [2c29e9571dc1e97d4794a9539a1d142ab33c0834] # # add_file "wiki/FeatureRobustRepository.moin" # content [a8f91a82b8581a5310e3e437d19a0b131afd9b36] # # add_file "wiki/FeatureSignedRevisions.moin" # content [a4a5100a01dd26c8aa483a89a7fbfdb886eac4c3] # # add_file "wiki/FeatureSymlinks.moin" # content [2a3964d71fbc071f92452d34365946fd56283c88] # # add_file "wiki/FeatureVendorBranches.moin" # content [f03506ca59fbef2f3df1f0fed561f86dd26fbe4a] # # add_file "wiki/FeatureWebInterface.moin" # content [9157dd1e6ad73fddb4056fe1dc4e1af212c128fb] # # add_file "wiki/FileSystemIssues.moin" # content [8d73f3572a576b94a792214523e2ae55fd329fa9] # # add_file "wiki/ForSide.moin" # content [e919705b36da5a0e07b8879015d678ae520188f2] # # add_file "wiki/FrontPage.moin" # content [b460fb25f23b4ad4515e8388f444438cb7e85f54] # # add_file "wiki/FutureCryptography.moin" # content [c98562ff69dfb2f85d5f1bce968b570253e1262e] # # add_file "wiki/Glossary.moin" # content [2a6b1a782845668a8250f7d73e7871544d1b7fba] # # add_file "wiki/HistoryBlueSky.moin" # content [8755486b8b434b2ef10e8267edcf4b216f226b91] # # add_file "wiki/Hosting.moin" # content [f13962875f0a802cf96b0190b44fba8db85f78d0] # # add_file "wiki/HugoMills.moin" # content [505ee089bf7588807478d05b5e3daea0b28ceab4] # # add_file "wiki/I18nL10n.moin" # content [68d2b64f1651c8e1036990aecaaf2b3fc361dcd1] # # add_file "wiki/IPv6.moin" # content [5c8384ba7aecb04feff53eb8ea9791b14bfadd61] # # add_file "wiki/InterfacesFrontendsAndTools.moin" # content [9d842ffbb7c7c1a76eba9a74436614bc7fb392fc] # # add_file "wiki/JackLloyd.moin" # content [871bb9517356b15024d2d785a7cb2994d87cb9a2] # # add_file "wiki/JustinPatrin.moin" # content [fc157c5c6a1ddddcdf5b3d116d1fa4ab6855dcf8] # # add_file "wiki/KeystoreFiles.moin" # content [9ca54de5971395feff06791195b07f3d82749565] # # add_file "wiki/LineEndingMunging.moin" # content [227520a6a479c07721cd8753ada4a2a806ae7c58] # # add_file "wiki/LocalBadContent.moin" # content [27f2a5b0e0af8f560a09c4f2efa863a8e9c8c821] # # add_file "wiki/LocalSpellingWords.moin" # content [52cd2b7dc55f492820f6f6357902327a221550ec] # # add_file "wiki/LogUI.moin" # content [b8a27de826511801a77008d31d9e93ec2d9bb1ae] # # add_file "wiki/MagicSelectors.moin" # content [1654cc137b0c52beec758f8cde22a6ccd3f2c594] # # add_file "wiki/MarcelvanderBoom.moin" # content [09445b210958d54cefd5e0d8b2b7b865acbed17c] # # add_file "wiki/MarkusSchiltknecht.moin" # content [0ea0e61d51fbf2a64ba3c7c3def85883a906c7fd] # # add_file "wiki/MasterRepository.moin" # content [95dc91fde3a8d057195f4bedf3181612fbb6511e] # # add_file "wiki/MattJohnston.moin" # content [3f34326ea5c2e30679c576cca11ee94c90618a22] # # add_file "wiki/MergeViaWorkingDir.moin" # content [f2ded928aaad1eaee10c9ca1177b6ccc913b9210] # # add_file "wiki/MonotoneAndCVS.moin" # content [ce31a95fc059b739d1b6959a7ab8636a1da77924] # # add_file "wiki/MonotoneAndSSHAgent.moin" # content [6de639c4a4223c7946b29a7a6256c3efa6306185] # # add_file "wiki/MonotoneOnDebian.moin" # content [74cade89db734e6c06635b5d20515b2f98061797] # # add_file "wiki/MtnSummit/FAsciikReview.moin" # content [42448bd3402ac683fa617e2c93ca580d52f6f984] # # add_file "wiki/MtnSummit/FFunding.moin" # content [b23c08536eb2b6d7b9a4510dcc45ba935b0296ac] # # add_file "wiki/MtnSummit/FGibberish.moin" # content [a183b29fa1c64941b9299bd95cee3c5905ae12f7] # # add_file "wiki/MtnSummit/FIdeas.moin" # content [c2df25fb4e7f294e5938c667e096dfb68e9a0326] # # add_file "wiki/MtnSummit/FInterestAndDates.moin" # content [455a17ba1e9c10efbaeaadf82bcfc59fd794ed84] # # add_file "wiki/MtnSummit/FLogisticsNA.moin" # content [d8ed5b88b511e3bffaf431f642ae59cf1e733c11] # # add_file "wiki/MtnSummit/FNotes.moin" # content [9d01d9c867bb058636ed3c62fd2a435cecfa52e8] # # add_file "wiki/MtnSummit/FRooms.moin" # content [b359314b3b5faed165eb2c1dfbafdf67a90faf60] # # add_file "wiki/MtnSummit/FSchedule.moin" # content [bbb2538d1ef832e72016a1c1d5927019744fca2b] # # add_file "wiki/MtnSummit.moin" # content [6fb21628f57f8677432168c60a9b4e157acd7788] # # add_file "wiki/MtnSummit2008/Branches.moin" # content [31033a89afc9276ba317e955e29b8054ffd1e09c] # # add_file "wiki/MtnSummit2008.moin" # content [62317e59395c98bb7498aebafe440cbd42e531b1] # # add_file "wiki/MtnSummitWishes.moin" # content [3dd886fca22e33368fd892d8f41ed9794f275767] # # add_file "wiki/MultiParentWorkspaceFallout.moin" # content [dc38983f7b1169df55a274e92c3d58df71402b8e] # # add_file "wiki/NathanielSmith.moin" # content [2c3babbf105c306dea7691db1c86453d1f57da77] # # add_file "wiki/NeedReview.moin" # content [7802d12615e63bb9e76ff73ca4e98e6258b58455] # # add_file "wiki/NetsyncTodo.moin" # content [46b4213335f43878cb86ab4a08465e53d5bd5ef4] # # add_file "wiki/NonMergeConflicts.moin" # content [97d3215c1e4f1647494de48f2a8d70d52208afac] # # add_file "wiki/NotesOnTestingChangesetify.moin" # content [adcc28128e8232940ea82ff46f7e7b7263aaaa38] # # add_file "wiki/OldTestHarnessIssues.moin" # content [5e4daf36b863d61e5c10c8deec5e57e55d93db0f] # # add_file "wiki/OneBranchPerDbForServe.moin" # content [51fb4788c4638f5e5b3e721501075c82dce8f7e0] # # add_file "wiki/PartialPull.moin" # content [1a55554c7ba633cc3220ef20a9d669df2b301ce0] # # add_file "wiki/PathUI.moin" # content [5bea0fecd6ae3bf7463993cbb72cf96f121390da] # # add_file "wiki/PaulCrowley.moin" # content [022cce85a8f46c7d2d4d403280b4226dc4a0b536] # # add_file "wiki/People.moin" # content [8fe745665c2d9e04cef7b4756c9af4bd284de7da] # # add_file "wiki/PerformanceWork/SQLiteAnalyzeDiscussion.moin" # content [848a85c65c1c82f2ae2fb5b772d1841d0c2519bd] # # add_file "wiki/PerformanceWork.moin" # content [5c7c310a1718a5000d49a32ee0823cc299401e7a] # # add_file "wiki/PieceCache.moin" # content [e490d32fe5dbb194c58f839aa07fa64cf54eb5a4] # # add_file "wiki/ProjectsUsingMonotone.moin" # content [cc801e316277baa6308dc224a9a03efa82de21e7] # # add_file "wiki/QuickieTasks.moin" # content [16bd674a6e384f1de8b6a1d006609799e65a43de] # # add_file "wiki/ReferenceCard.moin" # content [bfea09f86757e7cec46ed21c55ac471cd09ec776] # # add_file "wiki/RelativePathnames.moin" # content [c1828742bdd9c07f669d763ce2d3498597dae3ba] # # add_file "wiki/ReleaseBranchPattern.moin" # content [eec7c8fc242845ff415ff2fff16df4821c6cfd9f] # # add_file "wiki/RevertUI.moin" # content [9bb3c91366b09d2626f26e835ac17c37d6632b0e] # # add_file "wiki/RevisionNumbering.moin" # content [04be28a189d3b53fe456809e29038c2bf4580c0f] # # add_file "wiki/RichardLevitte.moin" # content [338c6c65b6b6a87a461e13937af5dfff343ae1b8] # # add_file "wiki/RoadMap.moin" # content [cb919e5998280c11156ac303e1dd264dbc759792] # # add_file "wiki/RootDirRenaming.moin" # content [10da1643a55cfa941e84da21e3983cfdb6649f8d] # # add_file "wiki/RosterifyingPrivateBranches.moin" # content [a7ca9db78359567b2b21c45f27e716c884696558] # # add_file "wiki/RostersTodo/MarkAndMergeTests.moin" # content [41c378f4e9e463f206c7c7c686806dc77234f7d0] # # add_file "wiki/RostersTodo.moin" # content [48f735021a5ddfb160cfa8a8cd0b14d410ba4965] # # add_file "wiki/RunDbCheckOften.moin" # content [ce106627aa964ce149d6ba8624ea4cc0a1ea5fc8] # # add_file "wiki/SelfHostingInfo.moin" # content [f44b0f7324aa4048756217c3f8168343fdf25be1] # # add_file "wiki/SimplerIgnoreMechanism.moin" # content [c8ff6bdba6b82ea9b7104205116bb65828eaae51] # # add_file "wiki/SpeedySpeedySHA1.moin" # content [00d682bd6bc6dbe8d6d9ff47d02a3f67adee2d86] # # add_file "wiki/SummerOfCode2006.moin" # content [7a8e7def59200c3fd38e77b6bb54303b1adb703b] # # add_file "wiki/SummerOfCode2007/Ideas.moin" # content [4164eacc1d6622649e8490e4737ddcb78f3447dd] # # add_file "wiki/SummerOfCode2007.moin" # content [9516d219b27b3f14bb33d0d729a032398b76b34a] # # add_file "wiki/SurveyQuestions.moin" # content [ce00608fe5316b3c974ea16799c447e436d206bb] # # add_file "wiki/SymLinks.moin" # content [ae364b3afb663daead6e99719c80de138351d502] # # add_file "wiki/Talks.moin" # content [8505a9bc68fbb8415a0d16cbc81500fa0d34ef08] # # add_file "wiki/TestHarnessIssues/CleanUpTestNames.moin" # content [7f95da9e46a9cbdb7a64c47df6d947667d1f933d] # # add_file "wiki/TestHarnessIssues.moin" # content [a1322d09445f4fca5b58416fb8514a28d1b49f7d] # # add_file "wiki/TestHarnessUseCases.moin" # content [c293f190547afc0d234a42309fa767cf13db03fc] # # add_file "wiki/TestIntro.moin" # content [231b82e0722a708e2d2fa776becca84efa84d623] # # add_file "wiki/Testimonials.moin" # content [b8eda92829a0d2d19275abbd3010977819f100a1] # # add_file "wiki/ThingsStatusShouldShow.moin" # content [0ed0a1a91ae27b3e2b819f9c1e3f4ee44201de0e] # # add_file "wiki/ThomasKeller.moin" # content [282b6ad99a0fb8674ff1db1101ce4a533be79ae9] # # add_file "wiki/TimeStamps.moin" # content [ea646c9ac0cc113736513bd15e089ff2c812ac09] # # add_file "wiki/TipsTricksScripts.moin" # content [fa60235ec70caac788a5269d00cfbd26dd3c956f] # # add_file "wiki/TroubleShooting.moin" # content [65743a7cca512f11264f007606f07d2391d4885e] # # add_file "wiki/TrustDiscussion.moin" # content [918d6d812def7ca783883a45477a4ce04dc367cc] # # add_file "wiki/TrustFoundations.moin" # content [e073a5e7c41b6da60084dacf8a1dabe6715b402b] # # add_file "wiki/UnixAttribsAndSymlinks.moin" # content [11583439846b6220487f395c86122cac9ee5c00c] # # add_file "wiki/User%3AMetaeducation.moin" # content [dbbb2c70181ac97dfaf0967a5d1ee01a226332d8] # # add_file "wiki/UsingCerts.moin" # content [9b4a3164a0691d5aba3e204f0d48371cbdcbee93] # # add_file "wiki/VendorBranchPattern.moin" # content [c2d2272b8ed2f72f9c485e023a757fe45a23c87d] # # add_file "wiki/VersionedPolicy/FArchive.moin" # content [63b05f1787ea7c849eb363395a6b4fe7050ff0ad] # # add_file "wiki/VersionedPolicy/FComparison.moin" # content [f14d1727f008a301dfbd02c0d5deea0dfddca08c] # # add_file "wiki/VersionedPolicy/FGraydon.moin" # content [641a4364811070e7ca9ebb2abbf404891915adeb] # # add_file "wiki/VersionedPolicy/FInterface.moin" # content [c195373b3dbe23b46b87ace73a7240089f8a139d] # # add_file "wiki/VersionedPolicy/FSPKIWontWork.moin" # content [8226a01418a126a02e9c1db323940a79d1f165ec] # # add_file "wiki/VersionedPolicy/FWorkList.moin" # content [44a31f4c28b6ea711abaaf0ec6818b33a6ed67fa] # # add_file "wiki/VersionedPolicy.moin" # content [58c9884c44f9dbb0c8b7464952023abab0be290a] # # add_file "wiki/Win32DeviceFiles.moin" # content [656f9dd7656bc6c471fb6a65005fe254150da32d] # # add_file "wiki/WishList.moin" # content [bcf02f8871734b3f305c203752c38aea6f1c73dd] # # add_file "wiki/WorkspaceConflicts.moin" # content [74cbd44290b147c417e1f8f08eb86f95e32da065] # # add_file "wiki/ZeroConf.moin" # content [4b4bca4b49f668d8d0b74b582118d3bfcbb34393] # # add_file "wiki/ZipperMerge.moin" # content [ccfc87030e67fc1a285b328b4e4b74d84c1f29ce] # # add_file "wiki/elb.moin" # content [b415c8fa2c31eea6116bf260eb441a1228249b86] # # add_file "wiki/gwk.moin" # content [01740864701220850d18198cd541d35b77ca0207] # ============================================================ --- wiki/AlternativeOverview.moin 0029709cf3c3ad22cb68c8f3c6473a3be5e07790 +++ wiki/AlternativeOverview.moin 0029709cf3c3ad22cb68c8f3c6473a3be5e07790 @@ -0,0 +1,81 @@ +''(Though there is a [http://venge.net/monotone/docs/index.html Monotone manual], this alternative presentation of concepts may be of use. It might be possible to refine this into an article that is the appropriate size, scope, and neutrality to be suited for integration into the [http://en.wikipedia.org/wiki/Monotone_%28software%29 Monotone Wikipedia article].)'' + + +== P2P Database Basics == + +Monotone is a command-line utility which runs on many platforms, and is used to create and manage '''monotone databases'''. At a basic level, each ''monotone database'' can be thought of as storing archives of documents in directories on a file system. In this way of thinking, it is like a collection of ".zip" or ".tar" files. + +=== Archiving === + +Each archive snapshot is called a ''revision''. A directory can be added into the ''monotone database'' using a command called '''setup'''. When a new ''revision'' has been ''setup'' into a ''monotone database'', a number known as a ''revision ID'' is automatically generated to identify it. '''(eds: technically, setup remembers what database you want to associate with, but can't generate a revision id yet. revision id's are only ever generated by a commit)''' + +Unlike adding files to a ".zip" or a ".tar", a directory that has been ''setup'' into a ''monotone database'' retains a connection to that database and is known as a '''workspace'''. Hidden files in the ''workspace'' are used to remember the ''revision id'' that was generated. Because monotone remembers what files were extracted, you can issue a command called ''commit'' to generate another ''revision'' using the same list of files (unless told to do otherwise). + +=== Extracting === + +Once a ''revision ID'' is known, you may extract the archive that corresponds to that ''revision'' into a directory, using a command called '''checkout'''. If you want to extract an archive into a directory that already exists...use the '''update''' command. Just as with ''setup'', performing a ''checkout'' or ''update'' keeps a connection between a ''workspace'' and a ''monotone database''. +'''(eds: er, you can update in a workspace that already exists. i don't believe you can run update in any old directory and have it work.)''' + +=== Transferring === + +''Revisions'' can be transferred from one ''monotone database'' into another. The monotone application is able to run as a server and accept requests from another instance of monotone running as a client. These client requests can '''push''' ''revisions'' from the client's ''monotone database'' into one residing on the server. They can also '''pull''' ''revisions'' from the server and into a ''monotone database'' managed by the client. + +(NOTE: Technically, both the client and server could run on the same machine, allowing one ''monotone database'' to be updated from another ''monotone database'' on the same file system.) + +Once foreign ''revisions'' have been migrated into a ''monotone database'', you may ''checkout'' or ''update'' them to unpack snapshots of the files tracked by that revision. There is no need to be connected to the network to perform these ''checkouts'' and ''updates'', so long as the ''push'' or ''pull'' that moved the ''revision'' has been completed. + +The term '''sync''' refers to a command that ''pushes'' and ''pulls'' at the same time. It is slightly faster than performing the two in succession. ''Sync'' has the advantage of utilizing your up and down bandwidth simultaneously. (The implementations of ''push'' and ''pull'' are built upon a core ''sync'' routine, but in those cases one side skips out on actually sending anything.) + +Because a ''monotone database'' is actually a [http://sqlite.org Sqlite database], it is a single file that is binary compatible across machine architectures. A ''monotone database'' usually starts out empty and is filled using ''commits'' and ''pulls''. However, copying a pre-prepared ''monotone database'' that someone else has populated may be faster than running the push/pull commands yourself. + +=== Labeling === + +Security and network authorization in Monotone client/server relationships are managed by the use of cryptographic keys. It is also possible to add metadata onto individual ''revisions'' which is digitally signed, and this metadata is called a '''cert'''. Contributors may add as many of these signed ''certs'' as they like. Once a ''cert'' has been added it is not generally practical to remove it. + + +== Versioning in Monotone == + +Most of Monotone's interesting features are enabled by tracking a concept of how one ''revision'' relates to another in conceptual sequence. +'''(eds: technically the set of revisions forms a directed acyclic graph. don't know if that's appropriate to point out for your target audience or not. the fact that it is *acyclic* does matter though.)''' + +=== Hierarchy === + +During a ''commit'', a relationship is generally set up between a ''"child" revision'' (the new one being created) and a ''"parent" revision'' (that already existed in the ''monotone database''). If a ''commit'' is run and a ''parent'' is indicated which already has a ''child'', then the ''parent'' will have multiple ''child'' ''revisions''. + +These relationships enable commands like "get the next/previous ''revision''", as opposed to making the user keep their own list of ''revision IDs''. When a ''commit'' is executed, it is assumed that the ''parent'' is the ''revision'' that was last fetched from the database via ''checkout'' or ''update''. If no ''checkout'' or ''update'' has been run since the last ''setup'' or ''commit'', it is assumed that the parent of the new version is the product of the prior ''setup'' or ''commit''. + +(NOTE: For efficiency of implementation, Monotone uses ancestral relationships as a hint for how to store ''revisions'' efficiently. It is assumed that a ''parent'' and ''child'' will have a large amount in common and thus the database can store a "diff" instead of full copies of the changed files.) + +=== Merging === + +Often it's the case that users on different machines will be adding independent ''children'' to a ''revision'' which they both ''pulled'' from a common source. When these two ''children'' are brought together into the same database, it will be apparent that there is a ''parent'' with multiple ''children''. The existence of this fork in the ancestry is a clue suggesting an intention to '''merge''' together these ''revisions'' as soon as possible. When a ''merge'' command is issued between two ''revisions'', the resulting ''revision'' is a child of both--which ties up a "stray" leaf in the ancestry graph. + +The large ''revision id'' number which is generated to identify a ''revision'' (generated by either a ''commit'' or a ''merge'') is the product of a [http://en.wikipedia.org/wiki/Cryptographic_hash_function cryptographic function] of the file contents and the ancestry information. In terms of security, this means there's a strong assurance that any time someone mentions a ''revision id'' it can be verified as referring to the same data that the original speaker intended. Another consequence of naming ''revisions'' this way is that there are no conflicts at all if two users perform a ''merge'' or ''commit'' that generates identical results. They can ''push'' those identical ''revisions'' into a common ''monotone database'' without incident. + +As part of its operation, the ''update'' command will ''merge'' a ''revision'' into your current state, in those cases where you have not ''committed'' a ''revision'' for your local changes yet. This has the disadvantage of making it impossible to return '''(eds: your workspace)''' to the state prior to the ''update''. It is almost always more valuable to first ''commit'' your working changes, '''(eds: do the merge)''' and then ''update'' them '''(eds: them -> your workspace)'''. This provides a ''revision id'' that refers to your changes prior to merging, allowing you to extract or ''push'' your local changes if you needed to. + +=== Branches === + +One of the widespread uses of ''certs'' in Monotone is to provide a textual label known as a '''branch'''. By convention, branches are given names that are hierarchical, in order to facilitate the use of wildcard pattern matching. The ''push'' and ''pull'' commands tend to use these wildcards, and are a way of saying "''push'' or ''pull'' all the ''revisions'' which match this wildcard". The creation of a named ''branch'' is usually a way of expressing a temporary (or permanent) intention to create code that's not to be merged into the "mainline" of a project. This is especially useful for indicating ''revisions'' that are part of a parallel development of new, tricky, or disruptive code. + +Many of the monotone command-line parameters do not act specifically on ''revision ids'' but instead derive the relevant ids by querying for ''branch'' labels. There are benefits of using ''branch'' information which builds upon the ''cert'' system as opposed to raw ''revision id''s. The ''cert'' of a branch ensures that claims about a ''revision'' being the "latest" or the "most interesting one everyone should merge" can be tested cryptographically. (The commands don't happen to check these at the time of a ''pull'', but rather when a ''merge'' or ''checkout'' is being run.) + +One of the useful commands that can be run on a ''branch'' is to list its '''heads'''. These are the ''revisions'' that do not have any ''children'', which represent continuing independent paths of development within that ''branch''. Because branches are implemented using ''cert''s (and a ''cert'' can be put on any ''revision'') it is possible to label arbitrary ''revisions'' in the history as belonging to a ''branch''--giving it a new ''head''. These ''heads'' are typically ''merged'' together in a ''branch'', and they can be ''merged'' across ''branches'' using the '''propagate''' command. + +=== Histories === + +Currently, trying to ''push'' or ''pull'' a specific ''revision'' across ''monotone databases'' will also ''push'' or ''pull'' all ''revisions'' in its ancestry. This means that if you intend to join an existing project with considerable history, you won't be able to ''pull'' only the last few ''revisions''. There is no underlying technical reason why this needs to be the case, although there may be some implication in terms of the ability to verify the legitimacy of the cryptographic hashes if one is allowed to ''pull'' partial histories. + +A side effect of making frequent ''commits'' instead of using ''update'' is that this will create ''revisions'' that others are unlikely to be interested in, and which you may not wish to share. To keep from ''pushing'' these intermediate changes along when you ''push'' your final ''revision'' to others when they ''merge'', you can execute this procedure: + + * monotone diff -r starting_base_revision > /tmp/mydiff + + * checkout the base again + + * patch < /tmp/mydiff + + * commit + +'''(eds: this set of actions still doesn't make sense to me. i'm also not convinced that you should, as a practice, try to hide intermediate commits in this way. if you're primarily concerned about others trying to merge your commits too soon, just don't push until you are ready.)''' + +This makes ''revisions'' an acceptable way of tracing more minute changes to files, such as to ''commit'' many times during editing. ============================================================ --- wiki/AttrUseCases.moin 2d4a515f1570b9b0742bc0405a481340175fba3f +++ wiki/AttrUseCases.moin 2d4a515f1570b9b0742bc0405a481340175fba3f @@ -0,0 +1,23 @@ +Attributes are really powerful, but it's not clear what parts of monotone should respond to them, what should be hookable, etc. To figure this out, here are some use cases for attributes: + + * turn on content encoding/decoding + * built-in merger cares about this + * reading/writing working copy files cares about this + * turn on line ending munging + * built-in merger cares about this + * reading/writing working copy files cares about this + * custom mergers -- "invoke this program when I merge these openoffice documents" + * built-in merger cares about this (it shouldn't run) + * user mergers care about this + * turn on CVS-keyword munging + * reading/writing working copy files cares about this + * nested trees -- a magic attribute that says "hey, this placeholder directory here should have a check out of revision ..., branch ...", somehow plays nicely with updates and commits in that branch. + * this needs a more detailed design to understand + * "update" and "checkout" need to be hookable, at least, so the subtree can be updated/checked out + * reading working copy _attrs_ may need to care about this + * ...add more + +One thought immediately occurred to me when first starting to work with attributes: +Why are attributes not more like certificates? They seem to express the same type of 'statements about something' only about files instead of revisions. Starting with the .26 series of monotone, the attributes are attached to the first class objects of file and directory types, so to me it would make sense to treat attributes as certificates on those objects, with all the same rules that apply for certificates too with respect to signing, selectors, automating etc. + +I've been playing for a while with implementing bugtracking directly '''inside''' a working directory. Starting with the new attributes in .26 this has gotten a whole lot easier. Attributes can comfortably be used to say, when a bugreport is stored as a file in the working dir somewhere, attach extra metainfo to that bugreport through attributes. Having the bugreports directly revisioned and distributed like the code you're tracking bugs for has obvious advantages. ============================================================ --- wiki/AutoInodeprints.moin e08af3462cb1553add68a59e456e6ba9c3778b88 +++ wiki/AutoInodeprints.moin e08af3462cb1553add68a59e456e6ba9c3778b88 @@ -0,0 +1,6 @@ +Idea: on large trees, people uniformly will want to turn on inodeprints. It's a mildly reckless thing to do, but if everyone's going to make that trade-off, then making them all do it by hand it just obnoxious on our part. + +So, we should consider: + * should inodeprints be automatically enabled at some point (e.g., some size tree)? (this is by default, obviously you could force it always on or always off if you wanted to) + * is there any way we can retain (more) safety while doing this? + * idea: do more thorough checks on some random subset of files, each time we scan the workspace. by tuning how we do this, we should be able to get near the speed of pure inodeprints, while avoiding the catastrophic case where a missed change is never noticed (leading to bugs where the code works in one person checkout but not another's, etc.). ============================================================ --- wiki/AutomateMagic.moin 2724845adddeba413546d3b0de606e72b4edfe46 +++ wiki/AutomateMagic.moin 2724845adddeba413546d3b0de606e72b4edfe46 @@ -0,0 +1,21 @@ +=== Show log entries for a given SELECTOR === + +{{{ +$ mtn automate select SELECTOR | mtn automate toposort address@hidden | xargs -L1 mtn log --last=1 -r +}}} + +=== Query the root or tail revision of BRANCH === + +{{{ +$ mtn automate heads BRANCH | mtn automate ancestors address@hidden | mtn automate toposort address@hidden | head -n1 +}}} + +Optionally, add another {{{ | xargs -L1 mtn ls certs}}} to query for the certs of the revision. + +=== Find the base revision on another BRANCH === + +This is useful if you want to generate a diff between the current head of a branch (taken from current workspace, see the second sub-command) and the branch your work is based on (specified in the first sub-command: nvm in the example). + +{{{ +$ mtn au common_ancestors `mtn au select h:net.venge.monotone` `mtn au select h:`|mtn au erase_ancestors address@hidden +}}} ============================================================ --- wiki/AutomateVersions.moin 8fe4aed794a15346037232c734d1b406017aa7d6 +++ wiki/AutomateVersions.moin 8fe4aed794a15346037232c734d1b406017aa7d6 @@ -0,0 +1,64 @@ +The rules to determine if the release version identifier X.Y is raised or not, are as follows: + + * the major number X increments whenever a backwards incompatible change is made + * the minor number Y increments whenever any other change is made; it is reset to 0 when major number increments + * either the major number X or the minor number Y increases at most once per release + +== Interface Version Matrix == + +The following table should give you an overview at which time certain functionalities have been added or altered in monotone's automation interface. + +||'''monotone releases''' || 0.17 || 0.18 || 0.19 || 0.20-0.23 || 0.24-0.25 || 0.26 || 0.27 || 0.28 || 0.29 || 0.30 || 0.31-0.33 || 0.34 || 0.35 || 0.36 || 0.37-0.38 || 0.39-0.40 || +||'''interface versions''' || 0.0 || 0.1 || 0.2 || 1.0 || 1.1 || 2.0 || 2.1 || 2.2 || 3.0 || 3.1 || 4.0 || 4.1 || 4.3 || 5.0 || 6.0 || 7.0 || +||ancestors || || || A || || || || || || || || || || || || || || +||ancestry_difference || || A || || || || || || || || || || || || || || || +||branches || || || || || || || || A || || || || || || || || || +||cert || || || || || || || || || || || || A || || || || || +||certs || || || || A || || || || || || || || || || || || || +||children || || || A || || || || || || || || || || || || || || +||common_ancestors || || || || || || || A || || || || || || || || || || +||content_diff || || || || || || || || || || || || || || || || || +||descendents || || A || || || || || || || || || || || || || || || +||drop_attribute || || || || || || || || || || || || || || A || || || +||drop_db_variables || || || || || || || || || || || || || || || || A || +||erase_ancestors || || A || || || || || || || || || || || || || || || +||genkey || || || || || || || || || || || || || || || || || +||get_attributes || || || || || || || || || A || || || || || C || || || +||get_base_revision_id || || || || || || A || || || || || || || || || || || +||get_content_changed || || || || || || || || || || || A || || || || || || +||get_corresponding_path || || || || || || || || || || || A || || || || || || +||get_current_revision || || || || || || || || || || || || || || || || A [[FootNote(While the format of this command has not been changed between 0.39 and 0.40, the output may differ because the interpretation of the --depth option changed in 0.40 (previously: 0 = the node + its immediate children, now: 0 = only this node))]] || +||get_current_revision_id || || || || || || A || || || || || || || || || || || +||get_db_variables || || || || || || || || || || || || A || || || || C || +||get_file || || || || A || || || || || || || || || || || || || +||get_file_of || || || || || || || || || || || || || || || || || +||get_manifest_of || || || || || || A || || || || || || || || || || || +||get_option || || || || || || || || || || A || || || || || || || +||get_revision || || || || A || || || || || || || || || || || || C || +||graph || || || A || || || || || || || || || || || || || || +||heads || A || || || || || || || || || || || || || || || || +||identify || || || || || || || || || || || || || A || || || || +||interface_version || A || || || || || || || || || || || || || || || || +||inventory || || || || A || || || || || || || || || || || C || C [[FootNote(While the format of this command has not been changed between 0.39 and 0.40, the output may differ because the interpretation of the --depth option changed in 0.40 (previously: 0 = the node + its immediate children, now: 0 = only this node))]] || +||keys || || || || || A || || || || || || || || || || || || +||leaves || || A || || || || || || || || || || || || || || || +||packet_for_fdata || || || || || || A || || || || || || || || || || || +||packet_for_fdelta || || || || || || A || || || || || || || || || || || +||packet_for_rdata || || || || || || A || || || || || || || || || || || +||packets_for_certs || || || || || || A || || || || || || || || || || || +||parents || || || A || || || || || || || || || || || || || || +||put_file || || || || || || || || || || || || A || || || || || +||put_revision || || || || || || || || || || || || A || || || || || +||roots || || || || || || || || || || || || || A || || || || +||select || || || A || || || || || || || || || || || || || || +||set_attribute || || || || || || || || || || || || || || A || || || +||set_db_variable || || || || || || || || || || || || A || || || || C || +||stdio || || || || A || || || || || || B || || || || || || || +||tags || || || || || || || || A || || || || || || || || || +||toposort || || A || || || || || || || || || || || || || || || +||'''interface versions''' || 0.0 || 0.1 || 0.2 || 1.0 || 1.1 || 2.0 || 2.1 || 2.2 || 3.0 || 3.1 || 4.0 || 4.1 || 4.3 || 5.0 || 6.0 || 7.0 || +||'''monotone releases''' || 0.17 || 0.18 || 0.19 || 0.20-0.23 || 0.24-0.25 || 0.26 || 0.27 || 0.28 || 0.29 || 0.30 || 0.31-0.33 || 0.34 || 0.35 || 0.36 || 0.37-0.38 || 0.39-0.40 || + +A = Addition, B = Backwards-compatible change, C = Backwards-incompatible change + +If you like to get more information about certain command / format changes, please consult [http://monotone.ca/docs/Automation.html monotone's Automation documentation]. ============================================================ --- wiki/AutomateWishlist.moin f3bb3bdae39ddb18e4ede0eeaeddb6cea8abdb84 +++ wiki/AutomateWishlist.moin f3bb3bdae39ddb18e4ede0eeaeddb6cea8abdb84 @@ -0,0 +1,106 @@ +Missing (but useful) functions for the automate interface: + + * `ancestors`: limit the number of returned ancestors (like calling `parents` repeatedly) + + * `branches`: returns the names of all branches. => How should that differ from `mtn ls branches`? - It would be callable from an automate stdio connection. ['''Implemented'''] + + * `diff`: returns the unified diff between two revisions. ['''Partially Implemented as automate content_diff'''] + + * `roots`: returns all revision ids without parent. ['''Implemented'''] + + * `get_file_length ID`: returns the size of the specified file. + Currently one has to fetch the whole file in order to find out its length. + NB: monotone does not actually store this information; the implementation inside monotone would just involve fetching the whole file and then reading its length. So this is a little dubious; it would encourage people to do things that are actually _slower_ (like fetching both the length and the full file, instead of just calculating the length themselves) when trying to optimize. Fetching a single file twice in a row through 'automate stdio' is pretty cheap, though. + + * `get_file ID OFFSET LEN`: returns only partial file contents. + Might be handy for reading big files piecewise. + NB: monotone does not actually have this capability internally (because sqlite does not have this capability internally); each time you requested a chunk, monotone would have to read the whole file into memory and then just deliver the requested part. Of course, it would then keep the file in its cache, so requesting multiple chunks in a row would be reasonably cheap... but you still have the whole file in memory. Let's leave things that "might be handy" until there's a real program that needs the capability :-). + + * `get_option OPTION`: return the given option (where OPTION is "branch", "database", etc. - entries in _MTN/options) + Clearly, anyone that wants to know these things can just grep them out of _MTN/options - but that's not really supported and is messing about with what are really monotone's internals. Knowing the DB monotone would use for a given workspace would be useful for GUIs. + ['''Implemented'''] + +== Extensions to support Graphical User Interfaces == + +-- MarcelvanderBoom [[DateTime(2006-06-18T18:39:06Z)]] +Given the 'automate branches' example,the whole of the document linked to above, and the growing number of commands both in automate variety and in the normal interface (mtn heads for example), my wish would be that the 'normal' interface and the 'automate' interface become one; said another way: "get rid of the mtn automate command". Using a cmdline switch or a format specifier the output produced and the specifics of the effect can be steered. What 'callable from an automate stdio connection' means to a user: 'nothing'. + +To me: +{{{ mtn heads}}} +and +{{{ mtn automate heads }}} + +are the same thing, just formatted differently and as such i tend to look for an '''option''' to specify these formattings, not another '''command'''. Having something formatted as a plain rev list or basic io stanzas could be options to select quickly as they are used frequently. The document at berlios more or less says "give me all normal mtn commands, just in the automate interface" Why not do this in general? + +-- ThomasKeller [[DateTime(2006-08-28T10:33:00Z)]] +The only reason why all these commands must live inside the automation interface is because they need to be callable via automate stdio. If there would be a general refactoring which would allow the execution of any "normal" command via this interface, then this would be sufficient as well. Obviously if the automation interface would be removed in favor of a general implementation, one would need to think about where to move the current functionality from there, which does not exist in the normal interface. And for that purpose we'd need to make a big plan, and, I don't think anybody around here is keen on making big plans which take months to implement (if they're implemented at all). + + +== Automate Stdio Stream Mux == + +A large problem for current consumers of '''automate stdio''' is that this interface really only caters for the normal output of the command on the stdout stream. If the command produces some warning, errors, or even progress messages (like tickers, which may be useful for future automate commands), these are not well handled: + + * some errors and messages may interrupt the stdout stream, causing the client to get out of sync with the stdio record format + * where multiple commands are called, it can be hard to tell which command caused which warning/error on stderr. + * for either case, the content of the error message is not structured for program usage; it may even be changed based on the users language settings. + +To address these problems, some changes and clarifications to the '''automate stdio''' output record format are proposed. + +The current form has the following description: + +{{{ +The output consists of one or more packets for each command. A packet looks like: + +:::: + + is a decimal number specifying which command this output is from. It is 0 for the first command, and increases by one each time. + + is 0 for success, 1 for a syntax error, and 2 for any other error. + + is 'l' if this is the last piece of output for this command, and 'm' if there is more output to come. + + is the number of bytes in the output. + + is a piece of the output of the command. + +All but the last packet for a given command will have the field set to 'm'. +}}} + +It is proposed to change it as so: + +{{{ +The output consists of one or more packets for each command. A packet looks like: + +:::: + + is a decimal number specifying which command this output is from. It is 0 for the first command, and increases by one each time. + + is 0 for no-error, 1 for a syntax error, and 2 for any other error. no-error on the final 'l' packet (see below) for a command indicates success of the command; on earlier packets it means no error yet. Once an error has been detected and indicated with a packet with non-zero error value, no later packet should go back to 0. + + is an identifier for which output stream this packet represents, allowing multiple streams to be multiplexed over the channel. The following streams are presently defined; more streams may be added later. + + 'm' and 'l': the 'm' stream represents the normal stdout automate output of the command, formatted as described in the description for that command. The special 'l' value is described below. + + 'e': the 'e' stream represents any (unstructured) error message data. Internally, this maps to calls to the E() and N() print macros that would normally be written by the command to the program's stderr stream, if the automate sub-command had been called directly rather than via '''stdio'''. + + 'w': the 'w' stream represents any (unstructured) warning message data. Internally, this maps to calls to the W() print macro that would normally be written by the command to the program's stderr stream, if the automate sub-command had been called directly rather than via '''stdio'''. + + 'p': the 'e' stream represents any (unstructured) progress message data. Internally, this maps to calls to the P() print macro that would normally be written by the command to the program's stderr stream, if the automate sub-command had been called directly rather than via '''stdio'''. + +As needed, some of these (e,w,p) messages may be replaced with structured and well-defined error information for more direct interpretation by a gui frontend, not localised, on a different stream. + + 'p': informative progress messages from the command during execution. + + 't': ticker updates, as may be used by the gui to update a progress bar. The ticker stream is formatted as a series of lines, one for each ticker update. Each line contains :[/]. The is the ticker name, is the value, the optional is the max value (which may be used for percentage in a progress bar). + + is the number of bytes in the output. + + is a piece of the output of the command. + +The last packet for a given command will have the field set to 'l'. This packet indicates termination of all streams for the command. Any content in this packet is considered to be part of the 'm' stream. The in this packet is likely to be zero if there has been an error message that has prevented or interrupted normal output. + +If a client implementation gets a record for a stream type it does not recognise, the record should be ignored. + +}}} + +The multiple stream encoding allows the output of errors and warnings to be associated with the command that generated them, allows the communication path to always stay in sync, and offers the opportunity to add other stream types for other useful purposes in the future as needs arise. ============================================================ --- wiki/BasicIoFormalization.moin c0f2b9a879db4c1cb480a5cc71e2d75bd02c447c +++ wiki/BasicIoFormalization.moin c0f2b9a879db4c1cb480a5cc71e2d75bd02c447c @@ -0,0 +1,30 @@ +There's some debate on what the formal definition of basic_io should be, and in particular whether stanzas and lines should be first class items, or it should continue to treat all whitespace as identical, except with one special normalized form. + +http://colabti.de/irclogger/irclogger_log/monotone?date=2005-11-25,Fri&sel=117#l194 + +Attempting to tame this discussion a bit... + += Concrete issues = + +Things that need some sort of resolution: + + * whitespace normalization is AFAIK the ''only'' property that we don't verify is correct on incoming data. Since our policy is to verify everything, I would consider this a bug. + += Fuzzier stuff = + +Arguments to make stanzas/lines first class items: + * It seems unnecessarily confusing to have two somewhat different formats -- "basic_io" and "normalized basic_io"; especially since they're not clearly distinguished. + * It is nice if de facto and de jure standards line up. (The field of "usability" is basically the art/science of making this happen.) They don't right now; no-one who has simply been exposed to basic_io stuff has any idea that stanzas are insignificant. + * related: people will script monotone; they won't read the formal docs first + +Arguments to leave stanzas/lines as epiphenomena: + * meaningful whitespace is a generally bad idea. +{{{ + error cases with whitespace-sensitivity: pasting two stanzas together and forgetting to insert a newline. pasting two files together, inserting one extra newline, accidentally creating a "null stanza". wrapping. crlf conversion. +}}} + also, whitespace mangling (though "" blocks can also be mangled). += Empirical questions = + +Is one formalism easier to code up a quick parser for? + +Does one formalism lead to a parser that's easier to hack up a quick program around? ============================================================ --- wiki/BestPractices.moin 9e4acb167835df9bbc9c7b3c6553c0b43407d6b9 +++ wiki/BestPractices.moin 9e4acb167835df9bbc9c7b3c6553c0b43407d6b9 @@ -0,0 +1,14 @@ +There is more than one one way to get things done with monotone. Listed here is guidance in best practices in using monotone. Following these procedures will help you get the most out of monotone, and help avoid common pitfalls. + +||CommitEarlyCommitOften || Making smaller changes makes it easier for others to pluck them || +||DaggyFixes || Use the ancestry graph to save fix backporting and release management work || +||ZipperMerge || Use the ancestry graph to save branch integration and merging work || +||BranchNamingConventions || Name branches consistently || +||CreatingBranches || Best way to create branches || +||VendorBranchPattern || How to integrate other people's code into your project || +||BranchAssemblyPattern || Partition modules into branches, and assemble project with `merge_into_dir` || +||DevelopmentBranchPattern || Develop features on branches, and then merge || +||ReleaseBranchPattern || How to deliver a project to other people || +||DifferentDbsForServeAndWork || Keeping your work database and the monotone server's database separate || +||OneBranchPerDbForServe || Don't keep all of your eggs in one basket || +||RunDbCheckOften || Catch database corruption early || ============================================================ --- wiki/BranchAnalogy.moin 69abef4c1813f7a5818525da77e1d9fd086062e2 +++ wiki/BranchAnalogy.moin 69abef4c1813f7a5818525da77e1d9fd086062e2 @@ -0,0 +1,63 @@ +Monotone has a concept of branches that's internally quite different to some other VCS's. While it's very powerful and flexible, this has confused some users getting used to monotone's world. In particular: + + * in monotone, the revision history / ancestry graph is totally unrelated to the branch information: branches are not "editing branches" + * monotone branches can have gaps, or be otherwise disjoint in the revision history / ancestry graph + * different users can see the same branch as having different memberships + * even very old revisions can be added to new branches at any time + * the same revision can be on several different branches at the same time + * revisions can be on no branches at all + +This is because, in monotone, branches are represented by certificates on revisions - nothing more, nothing less. These certificates are assertions by monotone users about the branch membership status of the particular revisions. Because of the distributed nature of monotone, different users may be in posession of different branch certificates in their unsyncronised databases, or indeed they may wish to selectively trust only certain signers of branch certificates. Monotone provides some commands that use these branch certificates in particular ways to help select relevant revisions for common development tasks. Apart from these selection uses, branches are not in any way special to monotone. + +There are several important concepts in the above discussion. The following analogy may help new users grasp them. + + += Ancestry = + +The ancestry graph is like a family tree, documenting your genetic history. Each revision (person) has ancestors (parents). Most people have two (genetic) parents. In monotone most revisions record only one parent - the other parent is the unnamed working copy that had the changes being committed; revisions that result from merges have two recorded parents in the ancestry graph. + +The ancestry tree leading up to a revision is fixed. Once your genetic heritage has been determined, you can't really change it. Your ancestry is a fundamental part of the definition of your identity: + * in monotone, two revisions that took a different editing path to produce identical contents are different revisions, because they have different ancestors. + * However, if a new child is created by making the same changes to the same ancestor, this is the same revision - if identical changes are made to the same ancestor separately by several people, they produce identical clones (which are all the same revision). + * You can't really exist without your parents, either - in monotone, in order for a database to contain a revision, it has to also have copies of all of its ancestors, for a full genetic history. + +However, new children can be created from any revision at any time, and will be added to the ancestry tree. + +Children tend to look a lot like their parents, usually inheriting most of their genetic characteristics, plus a few changes (good or bad or otherwise). In software development, as in genetics, it's often very important to know the ancestry, because it tells you where certain characteristics and changes (mutations) came from, and which children are likely to have inherited those changes further down the family tree. + +Usually, when a new person is born, the doctor will sign a birth certificate containing various information about the person, such as the time and date of birth, and other similar things. In monotone, there are usually several certificates created on a new revision by default, and these certificates make similar statements about the new revision. + += Branch Membership = + +One of the certificates created by default in a new commit is a branch certificate, which is a statement about membership of the revision in a particular branch (which has a name). Branches are typically used to make statements about the suitability of particular revisions for particular purposes (such as being release-quality or experimental code, for example). Some commands in monotone look at branch certificates to help users select revisions for various purposes; these commands make working with monotone and common code-development practices more convenient, however you are not limited to only those common practices. + +Branch membership is like a nationality, or membership of a secret society: + + * In normal practice, it tends to run along ancestral lines: children often inherit the nationality of their parents. + * You can be a member of multiple societies, or hold several nationalities - even a nationality that neither of your parents hold, such as if you were born in another country. + * Not all of the members of a society are related to eachother, at least in recent history, though they may in fact share some long-distant ancestor. + * You can join a society long after you are born, if someone chooses to approve you as a member. + * When you join a new society, it might take some time for the membership records of distant chapters of that society to be updated to include you, so they might not recognise you as a member when you first turn up for a meeting. In fact, some remote chapters might not even recognise your chapter, and won't trust the membership records even when they do arrive - though they can always issue you a local membership certificate as well, if you satisfy them of your worthiness. + * it's quite possible (though perhaps a little unusual in practice) for people to not belong to any recognised nationality or secret society. + +In monotone, unlike some other systems, there is no requirement that branches follow ancestry lines. It's a common convenience to remember the branch name used to check out a revision, and use that as the default certificate when committing new children of that revision. Like above, this tends to result in most children being in the same branch as their parents, but this is a convenience only. + +You can start a whole new secret society of your own at any time by making a new branch certificate, either on an existing revision or as the initial branch certificate on your new child revision at commit time. Or you can leave off the branch certificate entirely and create a revision with no branch membership. + += Heads = + +In monotone, the "heads" of a branch are all the revisions with a trusted branch certificate for that branch, and with no descendents also in that branch (even if they do have non-member children elsewhere). + +These are the people who stand to inherit the secret society's treasured collection of ancient artifacts, which are passed down along family lines -- but only amongst society members! There can be multiple heads, because different members all around the world can each produce children whenever they like, and induct them into the society. As above, news of new children or memberships sometimes travels slowly, and it's often the case that two different local chapters each think two different people are the sole heir until news of others arrives. + += Merge = + +Just like for code development, it gets confusing for the society when there are too many inheritors, because the treasures really should stay together. It is best if the multiple inheritors can get together and produce a single heir with their combined genetic history to resolve this conundrum, though this doesn't have to happen immediately. + +Monotone includes a convenient command, `merge`, to find these heads and produce a rightful heir, complete with handy membership certificate. + += Propagate = + +Secret societies can be very focussed on a particular purpose, and if they stay isolated from developments in the wider world, they sometimes get a little in-bred; it's often a good idea for them to bring in some fresh genetic material from other parts of the ecosystem. This can happen when a society member produces a child with an outsider - the outsider might not join the society, but if the child is granted membership then their contribution has been added to the genetic pool of society members (and the child will be a new head for the branch, standing to inherit the ancient treasures). + +There is a similar command to `merge`, called `propagate`, to do exactly this. It works just like `merge`, except it looks in different places when selecting potential parents: `propagate` takes the names of two branches (societies), and takes the heads of those societies to create a new child. The child will, by default, be granted membership of only one of the societies - but can of course join any others as well. ============================================================ --- wiki/BranchNamingConventions.moin ca8b98456a645a38e80fb0e3d262ae21f3c7a391 +++ wiki/BranchNamingConventions.moin ca8b98456a645a38e80fb0e3d262ae21f3c7a391 @@ -0,0 +1,145 @@ +There are a number of ways to create '''globally unique''' branch names. There's some debate about which one is best. + +Please add other options to all these lists, expand on pros/cons, add yourself to the Supporters list of things you like, etc... + +Keep in mind that several of the possible branch syntaxes require changes to selector syntax, so if there's a branch syntax you think is awesome, but all of the possible selector syntaxes that could be used with it make your teeth hurt... then the branch syntax probably wasn't so awesome. + += Branch syntax = + +[[Anchor(JavaStyle)]] +== Java style == + +Example: `net.venge.monotone`, `net.venge.monotone.cvssync`, `com.gmail.accountname.project` + +What we currently recommend. Many people object to the reversed domain names. No way to do email-based branches, though some use their email address for a "hostname". This only becomes a "problem" when an actual hostname shares the accountname *and* hosts monotone projects as well. + +[[Anchor(clennox1)]] + CraigLennox: Unfortunately, this style puts `net.venge.monotone.gcc4` and `net.venge.monotone.gui` in the same namespace relative to `net.venge.monotone`. At a minimum there needs to be syntax to disambiguate the ancestrial hierarchy from the categorical hierarchy, so that it becomes possible to avoid netsyncing much more than is necessary to get either a single project or a single line of development across multiple projects ('''especially''' when pulling from very large sites). + +Supporters: ["arcatan"], ChadWalstrom, ["gwk"] + +== Hierarchy by Separator == +There are a number of suggestions that consistently use the same general syntax to introduce hierarchy. The only difference between these suggestions is the separator character. The generic format is: + +Syntax: `{IDENTIFIER|FQDN|RFQDN|EMAILADDR}[{SEP}PROJECT[{SEP}SUBPROJECT[...]]]{SEP}{BRANCH}` + +The choice of the separator character has many implications, from selector character collision to filesystem side-affects during checkout. The generic benefits for this format include disambiguation between host name and branch name, and the ability to introduce project and sub-project hierarchy relationships between branches. The identifier preceeding the project and branch can be just about anything, as long as it has a reasonable chance to be evaluated as unique amongst the user base. + +=== Hierarchy by / === +(was "Sorta URL style") + +Example: `venge.net/monotone`, `venge.net/monotone/cvssync`, address@hidden/newproj` + +Much more familiar way to represent hierarchical structure. Makes the branch names look like URLs, which may be bad, in that people will expect to be able to browse to them over HTTP, for instance. (Though one could also take advantage of this by actually putting a document there.) Requires escaping branch name '`/`' characters in selectors. + +EricAnderson: we use: "domain-name"/"project-name"/"project-branch" for global branches and "email-addr"/"project-name"/"project-branch" for personal branches. The standard for the mainline "project-branch" is just main. The only difference from the above examples is that we standardized on always having three levels in the names, which made things map slightly better onto how people coming from CVS seemed to think about branches. It has an interesting effect of if you do checkouts, they automatically show up in directories organized like the above, which is somewhat nice. However, this auto-directory effect probably wouldn't happen on Windows because the pathname separator on windows is \ not /. We haven't had any problem with people thinking they could browse these. + + NathanielSmith: Since windows actually accepts both \ and / as directory separators, I think that probably would work after all. + +Supporters: MatthewNicholson, EricAnderson, DanielThompson + +=== Hierarchy by : === +(was "classic mac style") + +Example: `venge.net:monotone`, `venge.net:monotone:cvssync`, address@hidden:newproj` + +Suggested by RichardLevitte. Doesn't look similar to URLs and confuse people, while still allowing a more natural order to things. Requires changes to selector syntax. + +''Note by RichardLevitte:'' I don't agree that it requires a change to the selector syntax, as a domain name will always have at least one period. + +''Note by ChadWalstrom:'' I tested this on a Mac OS 10.4.x machine, creating a test branch named address@hidden:blah`. In the shell, the directory was correctly created as address@hidden:blah` upon checkout. It did not create a subdirectory as did the "/" character when chosen as a separator. However, when viewed in the {{{Finder}}} application, the directory was listed as address@hidden/blah`. The contradiction in representation of the folder name is confusing. The {{{Finder}}} does the correct thing when trying to descend into the directory, however. Practically speaking, this is cosmetic side-effect "bug". + +Supporters: RichardLevitte (obviously) + +=== Hierarchy by # === + +Example: `MyCompanyInc#project#branch`, `venge.net#monotone`, `net.venge#monotone#cvssync`, address@hidden + +The benefit of this format is that it doesn't really look like a URL and it doesn't require selector character change: `b:venge.net#monotone/a:address@hidden I don't believe this should have any impact on the filesystem checkout, given that the '#' is embedded within the name of the file and should be represented by all locales. Although the '#' is a meta character in POSIX shell for "comment", it does not get parsed as such if there is no space before it. + +Supporters: ChadWalstrom + +== Hierarchy by mixed separators == + +Using mixed separators would allow more flexibility in distinguishing between branches and subprojects. Examples: `net.venge.monotone/contrib/mtsh`, `net.venge.monotone#rosters#netsync` + +== monotone-specific URL style == + +Example: `monotone-branch://venge.net/monotone`, `monotone-branch://venge.net/monotone/cvssync`, `monotone-branch://address@hidden/newproj` + +Same as above, but sticking a scheme on like "monotone-branch" or something. That particular name is pretty cumbersome. Requires changes to selector syntax. + +"monotone-branch:" could be shortened to, say, "mtnb:". + +Cumbersome in general, but makes these full-fledged URLs, able to play in all the URL games etc. + +["elb"]: I would opt for mtn://, and stick with this -- then allow monotone to connect directly to the named host and fetch the named branch, or allow for a hostname to be provided. This is what opencm did, for whatever that's worth. + +DanielThompson: I would claim that adding a monotone-specific URL transport into the branch name is a bad idea. Supporting a mtn:// transport command line syntax sugaring for 'monotone pull' (or even 'monotone checkout') would be pleasant but integrating the transport type into the branch name would not assist with this and I would prefer the 'sorta URL style' to a strict URL. + + TimothyBrownawell: I would suggest supporting URLs of `mtn://hostname/branchname` . This would provide the convenience of having URLs without the problems of having the transport type or host name be part of the branch name. + +== standard URLs style == + +Example: `http://venge.net/monotone`, `http://venge.net/monotone/cvssync` + +Similar to XML namespaces, that have (generally http://) url, though the URL is itself often basically meaningless (if retrieved, it may have no content, or trivial content). Requires changes to selector syntax. Not clear how to do email-based names (`mailto:address@hidden/newproj`? `mailto:address@hidden) + +May be confusing. + + * ["arcatan"]'s thoughts: Let's not use branchs names which look like standard HTTP URLs if they're aren't standard HTTP URLs. If branch is called `http://venge.net/monotone/`, I want to be able to actually pull the repository over HTTP from `http://venge.net/monotone/`, then. + +Supporters: + +== URI/URN style == + +Example: `mtnb:venge.net/monotone`, `mtnb:venge.net:monotone/cvssync`, `mtnb:address@hidden:branch/name/here` + +Suggested by Hugo Mills. Abstracting away from http:// URLs, so it's obvious that it isn't going to resolve directly in a browser, but still keeping the general form of URIs. Requires changes to selector syntax. + +Supporters: + + +== emails galore == + +Example: address@hidden, address@hidden, address@hidden + +{{{ + If we were to recommend something, I'd suggest a convention -[.sub[.]]@. E.g. address@hidden and address@hidden + Sorry, that's -[.[.]]@ +}}} + +Suggested by Nathan Myers. Simple, avoids fuss about selectors. Seems unlikely that people will actually register new emails for every branch, and it seems rude to have things that look like email addresses but aren't. +/ += Selector syntax = + +The basic problem is that selectors currently have both {{{:}}} and {{{/}}} as magic (meta) characters. These are the two characters that aren't already reserved by the shell (like {{{`'"!#$&*()<>?;"\|[]%}}}) or wanted for other things within selectors (like address@hidden which are all likely in email addresses and branch names). + +This is less of an issue with monotone version 0.27 and later. Selectors can now be escaped with a `\` character, which will cause special characters to be ignored by the selector parser. The `:` is still treated as a special character is certain cases. + +Possible replacement characters include: + * `~` -- only magical at the beginning of a shell token + * , + * possibly ^ -- it is magical in some contexts/some archaic shells, because it was the original pipe symbol. git uses it in a similar context. + * ''{{{%}}} -- only magical (in Unix) at the beginning of a shell token, no longer common in email addresses.'' -- Err, what about on windows, which does env-var substitution like %FOO%? + ''Good point. Well, {{{%%}}} would avoid that, or choosing a clause separator character not likely to appear in a variable name. (Windows passes the {{{%...%}}} construct unmodified if it doesn't match a defined variable).'' + +URL-like things require replacing /, which is used to separate multiple clauses in a selector. So we might end up with: + * `b:venge.net/monotone~a:address@hidden + * `b:venge.net/monotone,a:address@hidden + +The mac-style one requires replacing :, so we might end up with things like: + * `b~venge.net:monotone/address@hidden + * `b,venge.net:monotone/a,address@hidden + +== Straw poll == + +Stick in your name and your opinion: + + * HugoMills: The URL/URI-style names have the advantage that things like XML, RDF and OWL all expect such names, so you don't have to mangle or change anything later if one of those technologies is used in some tool. + * KennethPerry: Also if the URL/URI style names was used, things like a monotone kioslave for KDE would fit (similar to the svn:// kioslave). + * NathanielSmith: I kind of like the forms with `~` or `,` as replacements for `/`. The `~` is more visually distinctive, and `,` has already associated meaning of "sequencing" a la MagicSelectors (but disappears visually more easily). + * ChadWalstrom: Branch names should not be transport dependent or interfere with transport naming. I do think it's important to note that that conventions should work ''with'' but not be enforced ''by'' the tool, unless it is done via hooks in lua. GNU Arch enforced naming conventions for its branches, which reflected its historical storage mechanism: directories of tarballs containing (uber) patches. This met with a lot of resistance with potential users (and even current users, myself included), especially those not interested in learning the internals and "why's" of naming conventions. + * CraigLennox: I favour changing as little as possible while addressing the real problem of namespace overload (which I describe at [#JavaStyle Java Style] above). This ought to be achievable without having to change the selector syntax. + * ["gwk"]: Java style (I'm a Java programmer...) it's nice and easy to read and type no shift etc. + * ExampleUser: I think [....] ============================================================ --- wiki/BranchRenaming.moin a0d5788f425f769f52ee6e2beb1ffa1fc6c965cd +++ wiki/BranchRenaming.moin a0d5788f425f769f52ee6e2beb1ffa1fc6c965cd @@ -0,0 +1,78 @@ +''NB: patches to integrate this information into the manual proper would be gratefully accepted'' + += Renaming Monotone Branches = + +Branch renaming is not natively supported or encouraged in monotone, but if you feel you really need to do it, it is possible. Keep in mind, monotone is a distributed version control system. This means that even though you may rename a branch locally, unless every other database with that branch performs the same operation, the old branch will return the next time you do a `pull` or `sync` operation. + +The following commands can be used to rename a branch in your local copy. I would advise backing up the database before performing any of these operations. +{{{ +for REV in `mtn automate select b:OLDBRANCH`; do + mtn cert $REV branch NEWBRANCH +done +mtn db kill_branch_certs_locally OLDBRANCH +}}} + +If your branch names contain '/' characters, either escape the '/' characters or use the shell snippet below. +{{{ +for REV in `mtn db execute "SELECT id FROM revision_certs WHERE name = 'branch' AND value LIKE 'OLDBRANCH'" | grep ^[0123456789abcdef]*$`; do + mtn cert $REV branch NEWBRANCH +done +mtn db kill_branch_certs_locally OLDBRANCH +}}} + +Basically this issues new branch certs for the branch you specifiy, and then the old branch certs are deleted. Be sure that the rename was successful (check with `mtn log`, `mtn list branches`, etc.) before issuing the `mtn db kill_branch_certs_locally` command. + +Note: You will have to enter your password once for every branch cert. To avoid this you can create a password hook in your `.monotonerc` file or use `yes PASSWORD | mtn cert...`, although that is not very secure (users can use ps aux or read your .bash_history to get your password). The ssh-agent integration available since mtn 0.34 is probably a solution to this, too. + +CraigLennox: These may fail with an "`argument list too long`" error if the branch contains a very large number (i.e. thousands) of revisions. You can get around that limitation by replacing instances of +{{{ +for REV in `mtn cmd args...`; do +}}} +with +{{{ +mtn cmd args... | while read REV; do +}}} + += Branch Renaming Script = +Here is a script that can be used to rename branches, including names branch with `/` characters in them. Be sure to backup your database before using it. You must set the MTN_DB environment variable to the location of your database. + +{{{ +#!/bin/bash + +set -e + +if [ -z "$1" -o -z "$2" ]; then + echo "Usage: $0 old.branch.name new.branch.name" 1>&2 + exit 1 +fi + +if [ -z "$MTN_DB" ]; then + echo "MTN_DB not set" 1>&2 + exit 1 +fi + +# use sed here to escape '/' characters +OLD=$(echo $1 | sed -e '{s/\//\\\//g}') +NEW=$2 + +for REV in `mtn -d $MTN_DB automate select b:$OLD`; do + mtn -d $MTN_DB cert $REV branch $NEW +done +mtn -d $MTN_DB db kill_branch_certs_locally $1 +}}} + + += Using A Ruby Shell To Manipulate Branches = +Using a ruby (or perl or python) shell can be a very convienient way to solve problems. +{{{ +% irb +irb> certs=`mtn automate select b:com.kiatoa.matt.rails`.split +=> ["0c597195698413293cc49691b0301b7f41af8be8", "17212d1b8058418432cf964754a2b08e16701e78", .... ] +irb> illegal="b715c|af49e0|7d7f" +irb> certs.each do |c| + if ! c.match(/^#{illegal}/) + system "mtn cert #{c} branch com.kiatoa.matt.rails2" + end + end +}}} +This allowed me to make a new branch with a head removed that I couldn't figure out how any other way to resolve. ============================================================ --- wiki/BranchStatuses.moin 812a0cacf85649e9048dd5565cc999419caeba14 +++ wiki/BranchStatuses.moin 812a0cacf85649e9048dd5565cc999419caeba14 @@ -0,0 +1,252 @@ +Currently active development branches: + += n.v.m.cvssync (outdated) = + +Contact: ChristofPetig + +Adds two-way syncing with (remote) CVS servers + +Status: Christof (and his collegues) use this branch for their daily work against their CVS servers, so it's definitely usable. Documentation is available. + +Open issues: the data structure (map) has difficulties and is inefficient for large (>1000 changesets) repositories; propagates gather too much changelog info; most problems arise when $Id$ tags get expanded differently; not yet reindented with GNU style. + +See also CvsSyncHints. + += n.v.m.cvssync.refactor = + +Contact: ChristofPetig + +A re-implementation of the cvssync architecture to be more modular, including a separate external process that interacts as a cvs client. + +Status: +What is done: + * mtn_cvs pull, push and takeover work with side branches and all sorts of strange setups (see tests) and are now attribute based + +What needs to be done: + * implement changed files + * implement sane branch connecting (or share with cvs_import) + * share the changeset-ification logic with cvs_import (I use the most simple approach for now) + * write documentation + * write migration helpers for the old branch + +What can be put into mainline: + * the piece_table abstraction can be shared with cvs_import (once I had committed the change) + * all automate extensions (the synchronization commands are about to change again to use attributes, so they might wait) + * the mtn_automate class (C++ wrapper library to access monotone via automate) + * the mtn_cvs directory infrastucture can be put into mainline but can wait as well until it's finished + += n.v.m.git = + +Contact: PetrBaudis + +Adds two-way syncing with git repositories (unix only). + +Status: I'm not quite sure. Petr? (ms) hasn't been touched for awhile, stalled. + += n.v.m.levitte.select-heads-of = + +Contact: RichardLevitte + +Adds an H: selector that runs erase_ancestors over the set determined by the rest of the selector. + +Status: Blocked on figuring out the right way to integrate this cleanly with the rest of the selector functionality. See MagicSelectors. + += n.v.m.levitte.usher = + +Contact: RichardLevitte +Created: 2006-02-28 + +The purpose of this branch is to add a suite of tests for usher and make it a supported program instead of just a contributed thingy. + +Status: Work in progress + += n.v.m.experiment.iface-refactor = + +Contact: NathanielSmith + +Some experimental UI and doc tweaks, in attempt to make things more streamlined and friendly to new users. + +Current changes: "setup" is renamed to "new_project". "pull" and "setup" have --new-db switches, avoiding the need to "db init" in almost all cases. Tempted to rename "genkey" too... + +Todo: get feedback; update docs accordingly; write tests + +Status: Work in progress. + += n.v.m.annotate = + +Contact: EmileSnyder + +Staging branch for work on the "annotate" command. As of 2006-01-30, there is work in progress on implementing per-file-DAGs of the revision graph in the db so that you can walk just the portion of the full graph in which changes were made to a given file. + +In order to try it, you must migrate your db and then run 'monotone db filedagify' on the database of interest. + +Todo: write tests for schema migration, fix kill_rev_locally to get rid of the node_revision_ancestry entries as well, figure out why new annotate is not identical to the old implementation, extend to handle all types of file changes (renames and attr changes) so it can be used to speed up restricted log too, roll filedagify into the migration? + +Status: Work in progress. + += n.v.m.debian = + +Contact: MatthewNicholson + +This branch adds a monotone-server debian package and also includes some tweaks to the existing package like installing the bash completion files. This package handles creation and management of a monotone database and key pair and also includes scripts for stopping and starting the server. The package will also attempt to do db migrate and similar operations if necessary during upgrades. + +Status: Merged into mainline. + += n.v.m.cvsimport-branch-reconstruction = + +Contact: MarkusSchiltknecht + +Features a graph-based cvs import algorithm, loosely based on the concepts of cvs2svn 2.0. + +Status: Still close to completion :-) - for more details, see CvsImport + += n.v.m.experiment.db-compaction = + +Contact: MarkusSchiltknecht + +A branch for trying out things from DatabaseCompaction. It has been used for turning hex encoded hashes ones into binary data in the database. That change has landed on mainline on 31.03.2008. + +Status: landed on mainline + += n.v.m.experiment.encapsulation = + +Contact: ZackWeinberg + +Removed the app_state from lots of places, instead we only pass down the required objects, which were formerly held in the app_state. These include: the lua interpreter, the database, the key store and the options. + +Status: landed on mainline + += n.v.m.partialpull and n.v.m.gaps = + +Contact: ChristofPetig and MarkusSchiltknecht respectively + +Both branches are about partial pulls, i.e. storing only revisions newer than those of a certain horizon (including them). See PartialPull for more information and a nice illustration. Both branches introduce some form of a sentinel, which covers an inexistant or incomplete revision. The difference for n.v.m.gaps is, that these sentinels don't just cover all revisions from the covered one until the root (null revision), but to any arbitrary revision, from which we have the revision data again. + +For more information, see this mailing list thread here: http://lists.gnu.org/archive/html/monotone-devel/2007-05/msg00185.html + +Status: Experimentation + += n.v.m.botan = + +Contact: MarkusSchiltknecht or TimothyBrownawell + +This is the staging branch for Botan, i.e. where we manually propagate new upstream Botan versions to, before landing on mainline. See also botan/README.botan-monotone. + +Status: Botan version 1.7.4 landed on mainline. + += n.v.m.botan.system-switch = + +Contact: MarkusSchiltknecht + +Adds a --with-system-botan configure switch, to allow using the system provided copy of botan. Especially note, that the system provided library most probably features the assembler optimizations for SHA1, where as the bundled botan currently does not. + +Status: Experimentation + += n.v.m.svn_import = + +Contact: MarkusSchiltknecht + +An initial attempt at importing subversion repositories into monotone. Didn't touch that for a while, as the CVS importer is still bugging me. + +Status: Experimentation + += n.v.m.heights = + +Contact: ThomasMoschny + +Implemented RevisionNumbering. The branch also serves as testbed for developing and testing applications of the heights, e.g. fast restricted log and fast annotate. + +Status: Currently merged into mainline. + += n.v.m.revision_diff = + +Contact: ThomasKeller + +Replaces "automate content_diff" by a generic "automate diff" command which outputs the complete changeset (including node adds, drops, renames and attribute changes) in an generic basic_io format. The actual diff is included in a "data" stanza in unified diff format. + +Status: Stalled for quite a long time, because there hasn't yet been an consensus if this should really be the "official" format mtn should use to express external changesets - primarily because once this is set into stone we certainly want an "automate apply_diff" command to complement this functionality. We also still have to find a way to express binary deltas within this new format to make it really useful for the "apply_diff" use case. + += n.v.m.commit_without_-b = + +Contact: ThomasKeller + +An attempt to remove the --branch option from "mtn commit" and replace the functionality by a new "mtn branch" command which explicitely sets the branch stanza in _MTN/options. This basically works, but is not thoroughly thought through for now, basically because we loose the old branch information after "mtn branch", so subsequent commands like "mtn update" which still rely on the old_revision and the recorded branch name fail badly unless the workspace is committed again. So, what still needs to be done is + + 1. if mtn branch is triggered on an unmodified workspace, mtn commit should succeed and just add the new branch cert to old_revision + 1. if the branch is switched, the new branch name should be recorded as "new_branch" while keeping "branch" untouched unless commit happens, so "mtn update" and friends work properly + 1. mtn revert should remove any "new_branch" stanza from _MTN/options + 1. eventually "mtn branch" should be renamed to "mtn switch" and get some more functionality (i.e. if switched to a named, existing branch, update the workspace to the head of this branch) + +Status: Stalled, decide what to do with all that. + += n.v.m.experiment.informal_messages_to_stdio = + +Contact: ThomasKeller + +An attempt to bring warnings and informal messages properly encoded into automate stdio. + +Status: Doesn't compile, not even alpha state. Hope to find some time for this on the next summit. + += n.v.m.automate-netsync and n.v.m.automate-stdio-ticker = + +Contact: ThomasKeller + +The former brings push/pull/sync to automate, while the latter tries to implement a stdio ticker so automate clients can actually monitor the progress of a netsync operation. + +Status: Unusable, should probably be suspended and/or redone from scratch (and maybe rethought even when / if n.v.m.nuskool gets ready?) + += n.v.m.lapo.color = + +Contact: LapoLuchini + +Making use of extra terminal features that may be available, such as colours (useful for diff and for asciik branch-lines). + +Status: rough and experimental + += n.v.m.automate_show_conflict = + +Contact: StephenLeake + +Goal: Provide simple flow to resolve non-content conflicts. + +Strategy: Add 'automate show_conflicts', to aid in determining how to resolve the conflicts. Then add options to merge to specify how to resolve the conflicts. + +Status: Just started; 'automate show_conflicts' works for "file added on left and right" case. Need to add all other conflict cases. + += n.v.m.experimental.win32_pipes = + +Contact: StephenLeake + +mtn sync file: and mtn sync ssh: do _not_ work reliably on Windows MinGW. + +There core problem is that Win32 does not support 'select' on pipes. + +This branch attempts to replace Win32 pipes by sockets. + +It fails, because ssh doesn't create sockets when it runs mtn. + +See comments in netxx_pipe.hh + +Status: on hold; use Cygwin instead, where things just work. + += n.v.m.experimental.win32_pipes_2 = + +Contact: StephenLeake + +Second attempt to fix mtn sync file: and mtn sync ssh: on Windows MinGW. + +See n.v.m.experimental.win32_pipes + +This branch attempts to fix the named pipe solution that is in the main branch. + +See comments in netxx_pipe.hh + +Status: on hold; no actual work beyond planning done. + += n.v.m.TEMPLATE = + +Contact: WikiName + +''Synopsis'' + +Status: ============================================================ --- wiki/BranchUI.moin 5897ef1838f3d13d94953899703b12e59a1c225e +++ wiki/BranchUI.moin 5897ef1838f3d13d94953899703b12e59a1c225e @@ -0,0 +1,26 @@ += Idea 1 = + +Have a command "branch". Usage: + * `monotone branch foo.bar`: switch working copy to be foo.bar (simply modifies MT/options). + * `monotone branch -r REV foo.bar`: mark rev REV as being in branch foo.bar (simply issues a branch cert) +Make `monotone commit` no longer accept a -b switch. + +In all cases give the user feedback on whether they have created a new branch or not. + += Idea 2 = + +"propagate " could note/warn that a new "newbranch" will be created, and behave the same as "cert h:somebranch branch newbranch". + += Idea 3 = + +Some user experience: + http://xaraya.com/pipermail/xaraya_devel/2006-January/002512.html + +Perhaps we should provide a `switch` command, which is similar to `update`, but: + * requires a branch argument + * if that branch exists, does `update -b BRANCH -r h:` + * if not, switches the working copy to be on BRANCH + += Idea 4 = + +''your idea here'' ============================================================ --- wiki/BugSquashingParty.moin 2e9e6b95e37d59ece66e2e74822907d7717a2d2a +++ wiki/BugSquashingParty.moin 2e9e6b95e37d59ece66e2e74822907d7717a2d2a @@ -0,0 +1,7 @@ +We're talking about having a Bug Squashing Party this weekend (November 26-27), with the goal of getting rosters merged. + +Participation requires some knowledge of C++ or at least shell, but no prior experience with monotone internals -- if you've been curious about getting more involved, this might be a great way to start! + +Ideally we'd have a big weekend-long online party, like Debian seems to, but since we're, err, a bit smaller than Debian, we should probably pick some core times... though of course one can and should squash bugs at any time :-). + +An important basic goal, and great way to help prepare for better-focussed work on the weekend, would be to spend some review time looking over the bugs currenly in the tracker, and updating them with current status if they don't fully reflect current reality. ============================================================ --- wiki/BuildBot.moin 7c24a658a87cec3360d3091a91c5a834a9cbbb3f +++ wiki/BuildBot.moin 7c24a658a87cec3360d3091a91c5a834a9cbbb3f @@ -0,0 +1,169 @@ +The buildbot helps us make sure monotone continues to work on lots of platforms and configurations, and debug what's going wrong when things break. + +General information: http://buildbot.net + +Our buildbot: http://monotone.ca/buildbot + +The way it works is that there is a single "buildmaster" that runs on a central server (`monotone.ca` in this case), that watches for new changes in the repo, and allocates work to "buildslaves". Buildslaves are run by helpful people out on the internet who have access to whatever weird configuration they'd like to make sure keeps being supported, and the cycles to spare on these boxes to do continuous rebuilds. + +We are always interested in getting new buildslaves; send a note to the list if you have one to offer, and we'll help you get it set up! + +Currently, a patch for the buildbot is required to support monotone. It has already been sent to the buildbot developers and will hopefully be applied to their mainstream code, soon. In the meantime, you can get the patch here: http://www.pastebin.ca/612470 + +An alternative is to grab the latest buildbot_*.tar.gz in http://guardian.lp.se/debian/testing/ . That's the version used for http://monotone.ca/buildbot/ and contains all patches that were needed to make it run properly with monotone (including the patches mentioned above). +For those running Debian, there's also the Debian package, built from the tar archive mentioned here, easily reachable with an appropriate choice between the following two sources.list lines: + +{{{deb http://guardian.lp.se/debian testing/ +}}} + +{{{deb http://guardian.lp.se/debian unstable/ +}}} + +See BuildBotWindows for setting up a Buildslave on Windows + += Setting up a Buildslave for Monotone = + + 1. Install Twisted from http://twistedmatrix.com/trac/ and buildbot from http://buildbot.sourceforge.net/ (and apply the above patch) + + 1. Create a new user to run the builds (very important): + On debian this is: + + {{{# adduser --disabled-login --disabled-password mtbuildbot +}}} + + On gentoo it is: + + {{{# adduser -s /bin/false -d /home/mtbuildbot -m mtbuildbot +}}} + + Other systems, I don't know, probably something like the above. + NOTE: The above seems wrong, in that later you'll need to 'su' to the user and you can't do that if it's disabled. I enabled mine and disabled it after everything was working. + + 1. Install a monotone binary into the new user's home directory; this is better than using the system-installed one, because it means that you don't have to worry about accidentally breaking the buildbot when upgrading. (On the other hand, it also means that whenever the netsync server protocol changes, you'll have to upgrade the copy of monotone installed here.) + + {{{# cp /path/to/working/mtn mtn +}}} + + You should let me know where the binary you want to use is located, since the path to the binary has to be set on the server side. + + 1. Create a buildbot instance: + + {{{$ buildbot create-slave slave-dir monotone.ca:9001 +}}} + + (replacing and by the name of this slave and the password that it was assigned). Note that you MUST run this command as the buildbot user you have created. The name and password have to come from the buildbot master admin, so ask on the list for a bot name and password. + + 1. Make sure that permissions are correct. The mtbuildbot user needs write access to slave-dir, and should not have write access to anything else. + +== Running the Buildslave == + +There are several ways to run a buildslave. Here are a few examples: + +=== Running the Buildslave with cron === + + 1. Start the slave now: + {{{# su mtbuildbot -c 'buildbot start slave-dir' +}}} + + 1. Check slave-dir/twistd.log to see it starting up and check for errors. + + 1. Set up the slave to be automatically started at boot: + {{{# echo '@reboot buildbot start slave-dir' | su mtbuildbot -c 'crontab -e -' +}}} + +=== Running the Buildslave with runit === + + 1. Install runit, http://smarden.org/runit or apt-get install runit or whatever. + + 1. Create a file called ~mtbuildbot/run: + {{{#!/bin/sh +cd $HOME/slave-dir +exec nice twistd --nodaemon --no_save -y buildbot.tac -l twistd.log +}}} + + and make it executable. (If you're on win32, you may need to add a --reactor=win32 argument to that command line. But then, you're probably not using runit in that case anyway, I guess...) + + 1. Make sure that permissions are correct. The mtbuildbot user needs write access to slave-dir, and should not have write access to anything else. + + 1. Start the slave now: + {{{# su mtbuildbot -c 'runsv .' & +}}} + + 1. Check slave-dir/twistd.log to see it starting up and check for errors. + + 1. Set up the slave to be automatically started at boot: + {{{# echo '@reboot runsv .' | su mtbuildbot -c 'crontab -e -' +}}} + += Monotone Buildbot Wishlist = + + * cygwin + * better BSD coverage (all we have ATM is one part time freebsd buildslave) + * better architecture coverage -- arm, m68k, hppa, ia64, ...? even another slave on ppc or x86-64 would be nice. + * better solaris coverage + * better windows coverage -- win95? win nt 4? there are many strange variations to this genus. + * a way to run the whole testsuite under valgrind and collect the results + * any other systems we don't have, but where you think monotone should work -- AIX? HP-UX? QNX? ReactOS? you tell me... + + += Setting up a Buildbot for your own Project using Monotone = + +Currently, you will need the above patch for buildbot to work with monotone. Make sure to make yourself familiar with the buildbot infrastructure, they have a nice manual: http://buildbot.sourceforge.net/manual-0.7.5.html + +You will most probably want to try the netsync hooks to notify the buildbot upon changes, see the monotone sources: contrib/monotone-buildbot-notification.lua + +Maybe, an example of a working configuration helps, here is what the master.cfg for the monotone.ca buildbot could look like: + + +{{{#!python +# -*- python -*- + +c = BuildmasterConfig = {} +c['bots'] = [("i386-debian-testing", "YOU-CHOOSE-A-PASSWORD-HERE")] +c['slavePortnum'] = 9001 + +from buildbot.changes.pb import PBChangeSource +c['sources'] = [PBChangeSource()] + +from buildbot.scheduler import Scheduler +c['schedulers'] = [] +c['schedulers'].append(Scheduler(name="all", branch="net.venge.monotone", + treeStableTimer=2*60, + builderNames=["i386-debian-testing"])) + +builders = [] + +from buildbot.process import factory +from buildbot.steps.source import Monotone +from buildbot.steps.shell import ShellCommand +from buildbot.steps.shell import Configure +from buildbot.steps.shell import Compile +from buildbot.steps.shell import Test + +f_unix_general = factory.BuildFactory() +f_unix_general.addStep(Monotone, + server_addr="monotone.ca", branch="net.venge.monotone", + monotone="mtn") +f_unix_general.addStep(ShellCommand, command=["autoreconf", "-i"]) +f_unix_general.addStep(Configure) +f_unix_general.addStep(Compile) +f_unix_general.addStep(Test, command=["make", "check"]) + +b_i386_debian_testing = {'name': "i386-debian-testing", + 'slavename': "i386-debian-testing", + 'builddir': "full-i386-debian-testing", + 'factory': f_unix_general, + } +c['builders'] = [b_i386_debian_testing] + + +from buildbot.status import html +c['status'] = [html.Waterfall(http_port=9000)] + + +c['projectName'] = "Monotone" +c['projectURL'] = "http://monotone.ca/" + +c['buildbotURL'] = "http://monotone.ca:9000/" + +}}} ============================================================ --- wiki/BuildBotWindows.moin deca46ad5b6288e334148a6940c4c3ca574a6fbb +++ wiki/BuildBotWindows.moin deca46ad5b6288e334148a6940c4c3ca574a6fbb @@ -0,0 +1,200 @@ += Setting up a Buildslave for Monotone on Windows = + +Here we explain how to run a buildbot on Win32 MinGW and Cygwin. + +The buildbot code is written in Python, so we need a Python +implementation. Ideally, we would use a MinGW Python implementation +for the MinGW buildbot, and a Cygwin one for the Cygwin buildbot. + +There is a Cygwin Python. It has some trouble during installation, but +it does work for the buildbot. + +There is no MinGW Python. There is a native Win32 Python, but it uses +"cmd.exe" to run shell commands; we want it to use MinGW bash. +Fortunately, there is a workaround for this (see below); we can use +the Cygwin Python buildbot to run MinGW bash scripts. + +We assume the tools required to build monotone on MinGW are installed; +see BuildOnWindows. + +== Install Cygwin == + + 1. Download the Cygwin installer from http://cygwin.com/, and run it + + 1. Install to "C:/", ''not'' the default "C:/Cygwin". The Cygwin installer says this is not a good idea; ignore that. + + The reason we do this is to make Windows file syntax match Cygwin syntax on the C drive. + Installing to "C:/" means Cygwin mounts "C:/" as "/", so Cygwin paths on the C drive are "/..." rather + than "/cygdrive/c/...". + + It may be possible to make the buildbot work with Cygwin installed at "C:/Cygwin"; I have not tried it. + + Note that MinGW is ''not'' installed at "C:/"; that would collide with Cygwin. This means bash scripts run by MinGW must use MinGW file syntax: "/c/...". + + 1. Include the following packages: + * Devel/autoconf + * Devel/automake + * Devel/boost-devel + * Devel/cvs + * Devel/gcc-g++ + * Devel/gettext-devel + * Devel/make + * Devel/monotone + * Interpreters/python + * Net/inetutils + * Utils/patchutils + + cvs and inetutils are required by autoconf, but are not included in the Cygwin installer dependency lists. + +== Install released MinGW monotone == + +We need a working monotone to pull the monotone source from the server. You can use either the Cygwin monotone, or the released MinGW monotone. In either case, the buildbot master needs to know where the working monotone is. It can be in PATH for the user that runs the buildbot. + +== Install buildbot == +We use /Apps as the source area; use another path if it suites you. + + 1. Download zope.interface-3.3.0.tar.gz from http://zope.org/Products/ZopeInterface/ + + 1. Download Twisted 2.5 source (''not'' the Win32 installer) from http://twistedmatrix.com/trac/. The file name is Twisted-2.5.0.tar.bz2 + + 1. Download BuildBot sources as patched for monotone from http://guardian.lp.se/debian/testing/. The file name is buildbot_0.7.5-1.1+RL20070709-2testing.tar.gz + + 1. Install zope: + 1. {{{ +cd /Apps +tar zxf /Downloads/monotone/zope.interface-3.3.0.tar.gz +cd zope.interface-3.3.0/ +python ./setup.py install +}}} + 1. This tries to compile some C code, but the link fails with the error: {{{ +/usr/lib/gcc/i686-pc-cygwin/3.4.4/../../../../i686-pc-cygwin/bin/ld: cannot find -lpython2.5 +}}} + + 1. Execute the link manually, changing '-lpython2.5' to '-L/lib/python2.5/config -lpython2.5.dll' + + 1. Repeat {{{ +python ./setup.py install +}}} + + 1. Install Twisted. + It has similar link problems, and 'runner' fails entirely, because it needs 'pmap_set', which should be in libc.a, but isn't on Cygwin. Fortunately, we don't need 'runner'. + + 1. {{{ +cd /Apps +tar jxf /Downloads/monotone/Twisted-2.5.0.tar.bz2 +}}} + + 1. Edit setup.py, comment out 'runner' from sumoSubprojects + + 1. {{{ +cd /Apps/Twisted-2.5.0/ +python ./setup.py install +}}} + This encounters similar link problems as above + + 1. {{{ +cd TwistedCore-2.5.0 +link manually +cd .. +python ./setup.py install +}}} + + 1. Install buildbot + 1. {{{ +cd /Apps +mkdir buildbot +tar zxf /Downloads/monotone/buildbot_0.7.5-1.1+RL20070709-2testing.tar.gz --strip-components=1 +cd buildbot +python ./setup.py install +}}} + +== Setup buildbot for MinGW == + +If desired for security, create a user account to run the buildbot. The buildbot runs code downloaded from the monotone buildbot server; there is a chance that will be hacked, or that the code is broken, and might do something harmful. + +It may also be helpful to have separate user for the buildbot, in order to set PATH properly. + +We create local scripts to run the monotone build commands in an Msys shell, because that's the only way to get a PATH that has only MinGW in it. + + 1. Set PATH for the user running buildbot to include Cygwin, but ''not'' MinGW. It may include the MinGW monotone, but that's not required. + + 1. Ask on the monotone mail list http://mail.nongnu.org/mailman/listinfo/monotone-devel for a bot name and password. In the message, include the path for running the working monotone. If it is in PATH, just say "mtn". Also be sure to say you are running a MinGW buildbot; it needs the buildbot master that uses local scripts to run commands. + Richard Levitte handles the buildbot master setup. + + 1. Create a directory that will contain the buildbot scripts and the monotone source and build directory. It must be writeable by the user running the buildbot. Here we'll call this "/Gnu/monotone-buildbot-mingw" + + 1. Setup the buildbot: {{{ +buildbot create-slave /Gnu/monotone-buildbot-mingw monotone.ca:9001 +}}} + The name and password are provided by Richard Levitte; they are stored in /Gnu/monotone-buildbot-mingw/buildbot.tac + + 1. One step in the monotone configure script wants to run the "cc" compiler. If that doesn't exist, we get a dialog box reporting an error in python, and the buildbot grinds to a halt. So we copy gcc.exe to cc.exe: {{{ +cp /Apps/MinGW/bin/gcc.exe /Apps/MinGW/bin/cc.exe +}}} + + 1. Create local shell scripts to run MinGW commands from Cygwin Python buildbot. Adjust the paths to match your setup. Note the MinGW syntax in some of the paths. + + 1. autoreconf-local.sh {{{ +/MinGW/bin/sh.exe --login -c /c/Gnu/monotone-buildbot-mingw/autoreconf.sh +}}} + 1. autoreconf.sh {{{ +cd /c/Gnu/monotone-buildbot-mingw/full-i386-win32-mingw/build +autoreconf -i +}}} + 1. configure-local.sh {{{ +/MinGW/bin/sh.exe --login -c /c/Gnu/monotone-buildbot-mingw/configure.sh +}}} + 1. configure.sh {{{ +cd /c/Gnu/monotone-buildbot-mingw/full-i386-win32-mingw/build +./configure +}}} + 1. make-all-local.sh {{{ +/MinGW/bin/sh.exe --login -c /c/Gnu/monotone-buildbot-mingw/make-all.sh +}}} + 1. make-all.sh {{{ +cd /c/Gnu/monotone-buildbot-mingw/full-i386-win32-mingw/build +make all +}}} + 1. make-check-local.sh {{{ +/MinGW/bin/sh.exe --login -c /c/Gnu/monotone-buildbot-mingw/make-check.sh +}}} + 1. make-check.sh {{{ +cd /c/Gnu/monotone-buildbot-mingw/full-i386-win32-mingw/build +make check +}}} + + 1. Edit /Gnu/monotone-buildbot-mingw/info/admin . Put in your name and email address. + + 1. Edit /Gnu/monotone-buildbot-mingw/info/host . Put in a description of your machine; for example "Monotone Mingw32". + + 1. If you have a firewall, allow outgoing ports 9000, 9001, 9010. 9000 is the buildbot master, 9001 is the buildbot master web page, 9010 is the buildbot master testing web page. + + 1. Run the buildbot: {{{ +buildbot start /Gnu/monotone-buildbot-mingw/ +}}} + + The first time it runs, it does some more setup. It logs everything to /Gnu/monotone-buildbot-mingw/twistd.log + + +== Setup Cygwin buildbot == + +A Cygwin buildbot uses the same Twisted installation as a MinGW buildbot. + +Because Cygwin is very similar to Unix, we can use the standard buildbot master scripts; no need for local scripts. + +There is one installation step required: Cygwin puts the boost library headers in /usr/include/boost-/boost , and monotone configure doesn't find them there. So we fix that: + + 1. Add a symbolic link to the boost library headers: {{{ +ln --symbolic /usr/include/boost-1_33_1/boost /usr/include/boost +}}} + +== Running the Buildslave == + +There are several ways to run a buildslave. If the Windows box is a dedicated buildbot machine, the simplest is to just run it from a Cygwin bash shell each time you reboot the box: + + 1. {{{ +buildbot start /Gnu/monotone-buildbot-mingw/ +}}} + 1. Check /Gnu/monotone-buildbot-mingw/twistd.log to see it starting up and check for errors. + +However, this buildbot will not automatically restart if the machine is rebooted due to a power failure or other problem. Running the buildbot as a service would accomplish that. However, the Cygwin cygrunsrv doesn't quite work for this; there are permission problems. ============================================================ --- wiki/BuildingOnMac.moin 8e18c22e92eb6a0b0d2bad3a4ea7065821787771 +++ wiki/BuildingOnMac.moin 8e18c22e92eb6a0b0d2bad3a4ea7065821787771 @@ -0,0 +1,93 @@ +Building Monotone on Mac OS/X + += Installing the toolchain = + +Monotone's makefile has to be generated using special GNU tools. Tiger (OS/X 10.4) does not have the required versions of these tools in the standard installation, though XCode 2.4.1 comes with an adequate version of the C++ compiler itself (older XCode versions have been known to be buggy). + +One way to get and build the latest versions of GNU tools is to get them from the [http://www.macports.org/ MacPorts (previously known as Darwin Ports)] project. Install the porting application from http://svn.macports.org/repository/macports/downloads/ and it will put a program called "port" into your ''/opt/local/bin'' directory. When you run this program as an administrator, it installs and builds the latest versions of GNU tools into that same directory. + +(if ''/opt/local/bin'' is not in your path, you can add it in a terminal shell by typing ''PATH=/opt/local/bin:$PATH'') + +Once you have installed the port tool, run the following commands (enter your password when prompted): +{{{ +% sudo port install gettext + +% sudo port install autoconf + +% sudo port install automake +}}} + += Getting the source = +Sometimes there is no pre-built binary of monotone on http://venge.net/monotone/downloads/ that is compatible with the version the development server is running. This means that if you want to synchronize and participate with the latest sources you will have to first build your own executable from a snapshot (''.tar.gz'' file). + +It's not actually that hard, and the instructions in the ''INSTALL'' file which come in the archive will walk you through it. When you install boost it may not be put into your library path, but you can tell the configure script that generates the makefiles where it is: +{{{ +% ./configure CPPFLAGS="-I(BOOSTPATH)/boost_1_32_0" LDFLAGS="-L(BOOSTPATH)/boost_1_32_0/libs" +}}} +If the executable you generate seems unreasonably large (over ~10 megabytes in size) then run ''strip monotone'' (or ''strip -S'' to keep basic symbols for debugging). + +Once you have a working monotone, then the following commands will let you grab the current development branch off the server: +{{{ +% monotone --db=mt.db db init + +% monotone --db=mt.db read <" for the addresses. + + + += Things to look out for = + +* As of 2006-01-22, boost from darwinports is not linked with the correct install_name [http://bugzilla.opendarwin.org/show_bug.cgi?id=5533 (darwinports bug 5533)]. Linking statically should still work, or compile it yourself + +* If you are linking to boost statically and ./configure can't see the libs, try running ''ranlib *.a'' on the Boost library files to update the archive indexes. + +* As of xcode 2.3 (gcc build 5341), -ggdb will generate dwarf debugging symbols. The size of a compile dir will be significantly (4x?) smaller with dwarf, so -ggdb is recommended. Note however that Shark doesn't seem to handle dwarf debugging symbols (as of 4.3.3) - you might want to explicitly give ''-gstabs''. + += Building a universal binary = +. +To create a universal binary, first you'll need to create fat boost libraries. Build two separate sets of boost static libraries, one with ''-arch ppc'' and one with ''-arch i386''. Then use ''lipo -create'' to produce a set of single .a files (use ''file libboost_foo.a'' to check that it worked). I then put header files in ''/usr/local/stow/boost-1.33.0-fat/include/boost'' and the .a files in ''/usr/local/stow/boost-1.33.0-fat/lib''. + +For configure, I've used: +{{{ +./configure CFLAGS="-O2 -mdynamic-no-pic -ggdb -gfull -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch ppc -arch i386" CXXFLAGS="-O2 -mdynamic-no-pic -fno-threadsafe-statics -ggdb -gfull -isysroot /Developer/SDKs/MacOSX10.4u.sdk -arch ppc -arch i386" --enable-static-boost=/usr/local/stow/boost-1.33.0-fat CPPFLAGS="-pipe -I/usr/local/stow/boost-1.33.0-fat/include" LDFLAGS="-L/usr/local/stow/boost-1.33.0-fat/lib -dead_strip" --disable-dependency-tracking +}}} + +You should then be able to just ''make'', though note that distcc doesn't seem to work with multiple ''-arch'' flags, since it uses the ''-E'' gcc option. The final output binary will be massive, so ''strip -S'' is recommended for distribution. An alternative approach to making a universal binary is to just build two separate monotone binaries, then ''lipo -create'' to stick them together. + +The ''-fno-threadsafe-statics'' works around a Apple gcc bug (4227885) that causes dramatic performance decreases accessing static variables. ''-dead_strip'' and ''-gfull'' are used to avoid linking in code that isn't used, reducing the binary size. ============================================================ --- wiki/BuildingOnSolaris.moin a3534a897e8126fde927e9c9966da24a9a3bf574 +++ wiki/BuildingOnSolaris.moin a3534a897e8126fde927e9c9966da24a9a3bf574 @@ -0,0 +1,153 @@ += GCC build = +The last experiences I had with that are 0.20-era and thus outdated. gcc, as delivered by sun is also a rapidly moving target with all kinds of bugs esp. in its copy of system headers and c++ headers. + +If you have some guidelines for gcc, please post them here. Feedback welcome. Thanks! + += Sun Studio build = +== Compiler == +The official build environment on Solaris is Sun Studio 10 and 11, of which the latter can be got at no charge on [http://developers.sun.com/prodtech/cc/products/get.html Sun's Website] (not free software). +You'll also need all [http://developers.sun.com/prodtech/cc/downloads/patches/ss11_patches.html available patches] for the compiler for your platform. + +== Boost == +If you use Boost 1.34 and Studio 11 with latest patches or Studio 12, no patches are necessary anymore! + +For older versions of Boost, you need [http://blogs.sun.com/roller/page/sga some patches] to the boost source itself, as its knowledge of sun studio's features is rather limited. You'll find the patches, as well as build instructions on the right pane on the site. [http://blogs.sun.com/roller/resources/sga/boost_1_32_0.patch Base patch] [http://blogs.sun.com/sga/resource/operations_posix_windows.cpp Additional patch to avoid segfaults in operations on large trees] + +== Compiling == +You'll need {{{CXXFLAGS=-library=stlport4 -features=tmplife -features=tmplrefstatic}}}. Adding {{{-Qoption ccfe -complextmplexp}}} might help in case of problems, but the documentation warns that it might produce wrong name mangling (I use it for the packages without any issues, though --PatrickGeorgi). + +=== Locales === +You might run into issues with libiconv if there's more than just the SUN version installed in a way that the compiler will pick it up. Unfortunately, the gettext macros for autotools get a bit confused by such a scenario and might try to link against the SUN libraries but using the GNU headers on build time, which fails. + +A solution is to configure with {{{--with-iconv-prefix=/usr --with-libintl-prefix=/usr}}} __and__ to remove the gnu iconv headers from any kind of compiler search path. + +If you don't have GNU iconv installed, you won't get locales support at all (but at least, it builds). The reason for that lies in the gettext macros that we inherited from gnu gettext, which only look for the GNU flavor (wasn't autoconf made for portability and finding out such differences?) + +If you really want locales, and want to avoid the trouble with gnu iconv, fetch the net.venge.monotone.portable-gettext-support branch. It should be complete enough to give you locales, but it's missing developer tools support without which it can't be merged into mainline (and thus, release). + +== Issues == +I don't know what other issues there are. If any come up, please post them here. + + += Running as Server = + +== Solaris Service Management Facility == +(address@hidden, 2007-06-11) + +Sun Solaris 10 introduced the "service management facility" (SMF) to replace the well-known, but arcane rc scripts. In addition to start, stop, and (optional) restart methods, it allows to define dependencies between services, sources of documentation and other meta information about the service. Each service is described in a single XML file that can be imported into the system's service repository. Here is the SMF XML file that I wrote for a monotone netsync service: + +{{{ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +}}} + +Save this to a file, say mtn.xml, and import it (svccfg import mtn.xml). + +The script assumes that mtn is installed in /usr/local/bin/, the user mtn and the group mtn exist (I like to give them uid 4691 and gid 4691, like the official IANA port of monotone), the directory ~mtn/.monotone/ contains the files monotonerc, read-permissions and write-permissions, and the repository is ~mtn/all.mtn (mtn -d all.mtn db init). Make sure these files are in place. + +(Hmm.. Some of that could probably be done with svc properties, or not? I might try that. --PatrickGeorgi) + +You also need to generate a keypair for the server (using mtn genkey), and the lua function get_passphrase(keypair_id) in monotonerc must return the passphrase so that mtn starts to serve without someone typing it in (see the mtn manual). + +You also need to configure the read-permissions and write-permissions files to accept users (see the mtn manual), and import their public keys into the database (using mtn pubkey on the client to export, and mtn read on the server to import). + +When all is done, enable and start the service (svcadm enable mtn) and start syncing! ============================================================ --- wiki/BuildingOnWindows/FVC8.moin cc2cfccb331742343b64e1836ef6dbd3d1436139 +++ wiki/BuildingOnWindows/FVC8.moin cc2cfccb331742343b64e1836ef6dbd3d1436139 @@ -0,0 +1,41 @@ += Installing the toolchain = +This section is preliminary setup--once this has been completed once, you can +rebuild monotone regularly using only the instructions in the next +section. + +||Package||Version||URL|| +||Visual C++ 2005 Express Edition||8.0||http://msdn.microsoft.com/vstudio/express/visualc/download/|| +||Windows Server 2003 R2 Platform SDK||3/14/2006||http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en|| +||Boost||1.33.1||http://prdownloads.sf.net/boost/boost_1_33_1.tar.bz2?download|| +||iconv||1.9.2||http://gnuwin32.sourceforge.net/downlinks/libiconv.php|| +||zlib||1.2.3||http://gnuwin32.sourceforge.net/downlinks/zlib.php|| + + * ''Newer versions of the tools listed above are likely to work without too much trouble.'' + +=== Installation instructions === + + 1. Visual C++ 2005 Express Edition - full install. + + 1. Windows Server 2003 R2 Platform SDK - full install. + + 1. Follow the Visual C++ 2005 Express Edition configuration instructions here: http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ + + 1. Update vsvars32.bat using the instructions here: http://boost.org/tools/build/v1/vc-8_0-tools.html + + 1. iconv - full install. + + 1. zlib - full install. + + 1. boost - follow the VS8 instructions here: http://boost.org/more/getting_started.html + += Building monotone = + + 1. Install a pre-built monotone binary from http://venge.net/monotone/downloads/ + 1. Follow the self-hosting instructions at http://venge.net/monotone/self-hosting.html to get a copy of the monotone repository. + 1. {{{ +$ monotone -d /path/to/monotone.db -b net.venge.monotone co monotone +}}} + 1. In Visual C++ 2005 Express Edition, open monotone/visualc/monotone.sln + 1. Select either the 'debug' or 'release' target from the toolbar dropdown. + 1. Review the C++ include path and Linker include path to ensure the paths to GnuWin32 (for iconv and zlib) and Boost are correct. + 1. Build the solution. ============================================================ --- wiki/BuildingOnWindows/FVisualC8.moin d598f53c08ce10e7405e13f34a375decb133f778 +++ wiki/BuildingOnWindows/FVisualC8.moin d598f53c08ce10e7405e13f34a375decb133f778 @@ -0,0 +1,42 @@ += Installing the toolchain = + +This section is preliminary setup--once this has been completed once, you can +rebuild monotone regularly using only the instructions in the next +section. + +||Package||Version||URL|| +||Visual C++ 2005 Express Edition||8.0||http://msdn.microsoft.com/vstudio/express/visualc/download/|| +||Windows Server 2003 R2 Platform SDK||3/14/2006||http://www.microsoft.com/downloads/details.aspx?familyid=0BAF2B35-C656-4969-ACE8-E4C0C0716ADB&displaylang=en|| +||Boost||1.33.1||http://prdownloads.sf.net/boost/boost_1_33_1.tar.bz2?download|| +||iconv||1.9.2||http://gnuwin32.sourceforge.net/downlinks/libiconv.php|| +||zlib||1.2.3||http://gnuwin32.sourceforge.net/downlinks/zlib.php|| + + * ''Newer versions of the tools listed above are likely to work without too much trouble.'' + +=== Installation instructions === + + 1. Visual C++ 2005 Express Edition - full install. + + 1. Windows Server 2003 R2 Platform SDK - full install. + + 1. Follow the Visual C++ 2005 Express Edition configuration instructions here: http://msdn.microsoft.com/vstudio/express/visualc/usingpsdk/ + + 1. Update vsvars32.bat using the instructions here: http://boost.org/tools/build/v1/vc-8_0-tools.html + + 1. iconv - full install. + + 1. zlib - full install. + + 1. boost - follow the VS8 instructions here: http://boost.org/more/getting_started.html + += Building monotone = + + 1. Install a pre-built monotone binary from http://venge.net/monotone/downloads/ + 1. Follow the self-hosting instructions at http://venge.net/monotone/self-hosting.html to get a copy of the monotone repository. + 1. {{{ +$ monotone -d /path/to/monotone.db -b net.venge.monotone co monotone +}}} + 1. In Visual C++ 2005 Express Edition, open monotone/visualc/monotone.sln + 1. Select either the 'debug' or 'release' target from the toolbar dropdown. + 1. Review the C++ include path and Linker include path to ensure the paths to GnuWin32 (for iconv and zlib) and Boost are correct. + 1. Build the solution. ============================================================ --- wiki/BuildingOnWindows.moin 7d4c4fde88cc5f8d1fd2b061be594734a33f6999 +++ wiki/BuildingOnWindows.moin 7d4c4fde88cc5f8d1fd2b061be594734a33f6999 @@ -0,0 +1,149 @@ +The officially supported build environment for monotone on Windows is [http://mingw.org/ MinGW]. The exact requirements are listed below. + +Building monotone under [http://cygwin.com/ Cygwin] is also known to work. monotone is also included as a package in all Cygwin mirrors and can be easily installed using Cygwin's [http://cygwin.com/setup.exe installer]. + +Building with Microsoft [http://www.microsoft.com/windowsserversystem/sfu/default.mspx Services For Unix] is untested, but would probably work without too much difficulty. + +Support for building using Visual Studio 8 is available, but we don't have a VC8 buildbot so sometimes the build is broken. See ["BuildingOnWindows/VisualC8"]. + += Installing the toolchain = + +This section is preliminary setup--once this has been completed once, you can +rebuild monotone regularly using only the instructions in the next +section. + +||Package||Version||URL|| +||MingGW||5.1.3||http://prdownloads.sf.net/mingw/MinGW-5.1.3.exe?download|| +||MSYS||1.0.10||http://prdownloads.sf.net/mingw/MSYS-1.0.10.exe?download|| +||msysDTK||1.0.1||http://prdownloads.sf.net/mingw/msysDTK-1.0.1.exe?download|| +||wget||1.9.1||http://prdownloads.sf.net/mingw/wget-1.9.1-mingwPORT.tar.bz2?download|| +||libiconv||1.11||http://prdownloads.sf.net/mingw/libiconv-1.11-mingwPORT-20070423-1.tar.bz2?download|| +||autoconf||2.59||http://prdownloads.sf.net/mingw/autoconf-2.59-mingwPORT.tar.bz2?download|| +||automake||1.9.5||http://prdownloads.sf.net/mingw/automake-1.9.5-mingwPORT.tar.bz2?download|| +||zlib||1.2.3||http://prdownloads.sf.net/mingw/zlib-1.2.3-mingwPORT.tar.bz2?download|| +||gettext||0.16.1||ftp://aeneas.mit.edu/pub/gnu/gettext/gettext-0.16.1.tar.gz|| +||boost||1.33.1||http://prdownloads.sf.net/boost/boost_1_34_1.tar.bz2?download|| + + * ''Newer versions of the tools listed above are likely to work without too much trouble.'' + +=== Installation instructions === + +The installer defaults put MinGW in c:\MinGW and MSYS in c:\Msys. However, later steps sometimes +install new items in c:\MinGW\bin, and sometimes in c:\Msys\bin. So it is difficult to ensure that the +new items are always first in path. Installing MinGW and MSYS both to c:\MinGW avoids this issue. However, +in this case the MSYS installer mistakenly renames 'make' to 'mingw32-make', so we need to change it back. + +msysDTK installs Perl, CVS, crypt, and other tools needed by the autoconf tools. The installed autoconf scripts are a little broken, so we need to manually fix them. + + 1. MinGW - install, accept defaults but add g++ on the package selection page + + 1. MSYS - install to same directory as MinGW (c:\MinGW), otherwise accept defaults + + 1. msysDTK - install into MinGW directory + + 1. Rename 'make' + 1. {{{ +$ mv /bin/mingw32-make.exe /bin/make.exe +}}} + + 1. wget + 1. {{{ +$ mkdir -p /usr/src +$ cd /usr/src +$ tar jxf wget-1.9.1-mingwPORT.tar.bz2 +$ cd wget-1.9.1/mingwPORT +$ cp -a wget.exe /mingw/bin +$ ./mingwPORT.sh +}}} + 1. Accept all defaults by hitting the enter key. The following steps also always accept all defaults. + + 1. libiconv + 1. {{{ +$ cd /usr/src +$ export SRCROOT=/usr/src +$ tar jxf libiconv-1.11-mingwPORT.tar.bz2 +$ cd libiconv-1.11/mingwPORT +$ ./mingwPORT.sh +}}} + + 1. autoconf + 1. {{{ +$ cd /usr/src +$ tar jxf autoconf-2.59-mingwPORT.tar.bz2 +$ cd autoconf-2.59/mingwPORT +$ ./mingwPORT.sh +}}} + 1. Open ''/mingw/bin/autoconf'' in an editor and change the following line: + * from something like {{{ +: ${AUTOM4TE='c:/mingw/bin/autom4te'} +}}} + * to {{{ +: ${AUTOM4TE='/mingw/bin/autom4te'} +}}} + + 1. automake + 1. {{{ +$ cd /usr/src +$ tar jxf automake-1.9.5-mingwPORT.tar.bz2 +$ cd automake-1.9.5/mingwPORT +$ ./mingwPORT.sh +}}} + 1. Open the files ''/mingw/bin/aclocal'', ''/mingw/bin/aclocal-1.9'', and all files matching ''auto*'' in an editor and delete ''c:/'' from all paths, as was done above for ''autoconf''. + + 1. zlib + 1. {{{ +$ cd /usr/src +$ tar jxf zlib-1.2.3-mingwPORT.tar.bz2 +$ cd zlib-1.2.3/mingwPORT +$ ./mingwPORT.sh +}}} + + 1. gettext + 1. {{{ +$ cd /usr/src +$ tar zxf gettext-0.16.1.tar.gz +$ cd gettext-0.16.1 +$ wget 'http://cvs.savannah.gnu.org/viewvc/gettext/gettext/gettext-runtime/intl/\ +localename.c?r1=1.15&r2=1.16&view=patch' -O localename_1.15-1.16.patch +$ cd gettext-runtime/intl +$ patch -p0 < ../../localename_1.15-1.16.patch +$ cd ../.. +$ ./configure --prefix=/mingw +$ make install +}}} + 2. If the wget command here fails, get the patch manually: {{{ +http://cvs.savannah.gnu.org/viewvc/gettext/gettext/gettext-runtime/intl/\ +localename.c?view=log +on version 1.15, click "select for diffs" +on version 1.16, click "diff to previous 1.15" +near top of page, click on "patch" +save file as c:/Downloads/mingw/localename_1.15-1.16.patch +}}} + + 1. boost; only need headers + 1. {{{ +$ cd /usr/src +$ tar jxf boost_1_34_1.tar.bz2 +$ cd boost_1_34_1 +$ cp -a boost /mingw/include +}}} + += Building monotone = + + 1. Install a pre-built monotone binary from http://monotone.ca/downloads/ + 1. Follow the self-hosting instructions at SelfHostingInfo to get a copy of the monotone repository. + 1. {{{ +$ mtn -d /path/to/monotone.db -b net.venge.monotone co monotone +$ cd monotone +$ autoreconf -i +$ ./configure +$ make +}}} + 1. And to run the testsuite: {{{ +$ make check +}}} + += Notes = + + * If the {{{./configure}}} step of the monotone build fails claiming your system is unrecognized while checking the build system type, it may be caused by {{{uname -s}}} returning a string containing MSYS rather than MINGW. This indicates that your build environment is in a special mode for producing MSYS binaries, which is not what you want when building monotone. See the following URL for a detailed explanation: http://www.mingw.org/MinGWiki/index.php/MsysBuildEnvironment + * If you get strange errors from perl when running {{{autoreconf -i}}}, check that you edited the paths correctly in aclocal-* and auto*. ============================================================ --- wiki/BuildingViaPkgsrc.moin 3b33859830e445df2fc2095c4b7ae2affa06f134 +++ wiki/BuildingViaPkgsrc.moin 3b33859830e445df2fc2095c4b7ae2affa06f134 @@ -0,0 +1,37 @@ +You can build monotone from source yourself on a number of platforms, and several pages in the wiki describe the process in some detail for various platforms. Monotone itself is pretty easy to compile, most of the detail on these pages deals with getting the various dependencies (like boost) installed first. You might like to try using pkgsrc to take care of all of these steps for you. + += About pkgsrc = + +The [http://www.netbsd.org/Documentation/software/packages.html pkgsrc framework] supports building third-party application software packages on a large number of platforms. It is the default package management system for [http://www.netbsd.org NetBSD] and [http://www.dragonflybsd.org DragonFlyBSD], and supports many [http://www.netbsd.org/Documentation/software/packages.html#platforms other platforms] as well, including Linux, Solaris, Irix and other Unix variants, and Interix (Microsoft Windows Services for Unix). + +If you're having trouble getting monotone for your particular system, either from the binaries provided by the monotone project, or from your platform's default packaging system if it has one, pkgsrc may well help. It might help with a lot of other tools as well! + +By default, pkgsrc sources are installed in `/usr/pkgsrc` and all tools and packages in `/usr/pkg` (of course these can be changed), so they don't interfere with other files and packages on your base system. This can be valuable even if your platform's packaging system does include a monotone package, but because of other operational reasons you need to maintain the system with older libraries and dependencies than monotone needs. By using pkgsrc, you can maintain parallel sets of dependencies for each purpose. + +Pre-built binary packages for a selection of platforms are maintained by volunteers, and these can save you some compile time if one happens to be available for you, but otherwise pkgsrc will fetch and build the package and all its dependencies from source for you. + += Bootstrapping pkgsrc = + +If you're running on NetBSD or DragonFlyBSD, your system already comes with the base pkgsrc infrastructure (and you're probably already familiar with using it). + +On other systems, pkgsrc needs to be bootstrapped. This process creates the tools used by the pkgsrc infrastructure to build and manage installed packages on your system. Unless you're already on a system very similar to NetBSD, one of these tools is likely to be the NetBSD make, which will be installed as `bmake` to keep it distinct from whatever make variant your platform has by default. On most platforms, you need to use `bmake` when working with pkgsrc Makefiles and packages. + +Bootstrapping [http://www.netbsd.org/Documentation/pkgsrc/platforms.html pkgsrc on other platforms] is described in detail in [http://www.netbsd.org/Documentation/pkgsrc/ the pkgsrc guide]. Bootstrapping can be done from source from within a pkgsrc source tree, or using a prebuilt [http://www.netbsd.org/Documentation/software/packages.html#binarydist binary kit]. + +After bootstrapping, there are some basic [http://www.netbsd.org/Documentation/pkgsrc/configuring.html configuration ] steps to do (though mostly the defaults will be fine), and then you can use pkgsrc to build and install thousands of useful third-party applications and tools. + += Building monotone = + +Once you have pkgsrc set up, installing [http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/devel/monotone/README.html the monotone pkg] and its dependencies is easy: +{{{ + # cd /usr/pkgsrc/devel/monotone + # bmake install +}}} + +There are also packages for many other InterfacesFrontendsAndTools that work with monotone. + +NetBSD is known for its broad portability, and strives for the same principle in pkgsrc. However, not all packages build on all platforms (though a surprising and ever-increasing number do), almost always because of underlying portability problems in the third-party software packages and dependencies themselves. Regular ''bulk builds'' of all packages are done on a number of platforms to catch such problems, but you may be unlucky. If you find a platform where the monotone package doesn't build, please submit a [http://www.netbsd.org/Misc/send-pr.html#submitting bug report] in the pkg category. + += using pkg_chk = + +Rather than adding and updating packages individually, the [http://pkgsrc.se/pkgtools/pkg_chk pkg_chk] utility can be used to remember which packages you want installed and keep them up to date. ============================================================ --- wiki/CarrotAndStick.moin cdde4c203d05d2a72f52e4e3b86a5991436cd507 +++ wiki/CarrotAndStick.moin cdde4c203d05d2a72f52e4e3b86a5991436cd507 @@ -0,0 +1,50 @@ +In order to form a more perfect UI... + += Empirical data = + +We don't actually know very much about how people use monotone in the wild! How silly is that? + +'''Plan''': keep a log in ~/.monotone/ of every command run. We should be very careful here to only log information that is not confidential. (E.g., need to check with community whether they consider branch names confidential. If very useful information is considered by some people to be confidentical, then fail safe -- default to not logging it, and provide a way for users who want to help, to enable more detailed logging. Alternatively, only enable the system at all if requested by a hook.) + +Log in particular start time of each run, the command run, plus provide a way for code to add arbitrary other things to the log. (Example: it would be useful to log, for each merge, information on whether conflicts were found, and what they are.) + +Provide a command to format this as an email message, for the user to look over and then send to some address. Make it clear what will happen to it (e.g., who will be able to see it). + +Another thing to log: whether we are running on a tty! + +Perhaps have monotone check the size of this file on startup, and if it is growing large, suggest the user send it in? Or possibly simply rotate it every once in a while, throwing out old stuff, so even if the user doesn't send it in, the space use is bounded? + += Involve the user = + +Once we have the above, add several commands: + * a way to express displeasure. `monotone punish`, `monotone stab`, `monotone die`, ...? + * a way to express pleasure. `monotone reward`, `monotone cookie`, `monotone kiss`, ...? +These commands react appropriately on stdout (whimpering, begging for forgiveness, pleasant surprise, ...?), and record (like any other command) to the log above. Actually, these should take comments on the command line -- part of the inspiration is the social practices around common IRC bots with their "~lart", "~stab", etc. commands, which are used to relieve frustration -- it is very common to see usages like "~lart paypal for sucking and not supporting Poland", "~lart X11 for two clipboards", etc. Take advantage of this and get a few more clues as to what the problem might be :-). + + * a way to make comments, that's a little less intrusive and ritual-laden as filing a bug report or sending an email to the list. `monotone whine`, `monotone complain`, `monotone say`, `monotone suggest`? `monotone oops`, tell people to make a note whenever they make a mistake, even if they think it's their fault? (give your comment on the command line, or else have it pop up an editor a la `commit`) + += Enabling = + +Perhaps the way to do this is to have the logging disabled by default, but have + * the --help for the above commands describe how to turn it on + * if any of the reward or punishment commands are run with it turned off, then work as normal, but also print a note saying that we won't know about their issues, and giving a reference for turning on the feedback functionality + * if any of the "purer" feedback commands are run with it turned off, then give an error message, and describe how to turn on the feedback functionality +The goal being to have it be as discoverable and require as little thought as possible -- and perhaps catch people right when they _are_ frustrated or happy, and perhaps will be most receptive to anything that suggests how they can help us help them. + += Getting the feedback = + +It is most convenient if the user does not have to do anything tricky to send feedback. Sending email is kind of hard. Perhaps we could use a HTTP(S) POST? (The [http://www.cs.wisc.edu/cbi/ CBI] folks get away with doing this after every program run. There are some sneaky bits too, like the response to the POST can tell the program to switch to a different URL, or shut down posting altogether -- useful if you want to stop receiving information, ever!) Probably we shouldn't do it every program run. Possibly we should do it after any of the direct feedback commands, and have a command that just sends feedback without prompting for a complaint. It might make sense, if the user has enabled this, to just automatically do the POST whenever our local buffer gets large enough... but if the network is down, this could cause monotone itself to misbehave in a user-visible way, which is bad for a pure feedback mechanism. + += Testing = + +What are the implications for testing? + + * We need some way to unconditionally disable this collection throughout the test suite + * We need to be able to re-enable it and force the output into a particular place, in order to test the collection + * We need some way to test the feedback mechanism -- how do we test POSTing to a URL? (I guess there are various ways to run a tiny HTTP server, e.g. in a few lines of python, or even something crazy involving bash and netcat...) + += Privacy = + +How much information do we record? Not file contents, obviously. Are file/directory names sensitive? Are branch and key names sensitive? Server names? changelog messages (which may occur on the command line, too)? + +Who has access to the recorded data? The two options I see are "everybody in the world" and "everybody who has convinced us that they have some minimal trustworthiness (slightly higher threshold than commit access)". Fancier things seem unworkable... ============================================================ --- wiki/CaseInsensitiveFilesystems.moin ed3bdd8d05b0625558c8a29e0d72abac456fc17a +++ wiki/CaseInsensitiveFilesystems.moin ed3bdd8d05b0625558c8a29e0d72abac456fc17a @@ -0,0 +1,18 @@ +Discussion: irc logger missed it, but, in #monotone around 2005-12-12T00:00:00 UTC. + += Problems = + + * I have a revision with files Potato.c and poTato.c. When I check it out, or update to it, on win32 or osx, either we silently screw things up, or we simply fail. (Find out which!) The latter would be better than the former, but neither is particularly appetizing. + * Proposed solution: extend MergeViaWorkingDir support to signal these like they were rename conflicts; this lets the user perform their checkout and then straighten things out. This also would be applicable in the cases where there is random junk in the user's tree, that we don't want to clobber on update. + * NB: this means that MergeViaWorkingDir needs to account for conflicts involving both versioned and unversioned files. And whatever code detects clobbering of unversioned files needs to figure out whether the file is in fact versioned, just under a different name. + * NB: this means we need to be able to handle n-way file name conflicts in the MergeViewWorkingDir machinery. + * A user on win32 or osx can do things like: "add Potato.c pOtato.c poTato.c potAto.c potaTo.c potatO.c" and have monotone cheerfully add 6 files. (I assume, have not tested this.) This will not corrupt history (except that they then will not be able to check their tree out unless they switch to a case sensitive filesystem, see previous), but it is certainly surprising and unhelpful. + * Proposed solution: One option is to find out whether the filesystem is case-insensitive (I think the only portable way may be to write out a file to MT/ and then try reading it again using a differently capitalized name?), and then write a chunk of code to make sure added files don't match each other, even with case-folded. This requires that we know the case-folding rules, which in this i18n world is really dubious (e.g., HFS+'s [http://developer.apple.com/technotes/tn/tn1150.html#UnicodeSubtleties rules] are guided by unicode but only fully specified by HFS+ itself). For another option, see below. + * "monotone add potato.c" when the file on disk is named Potato.c --> should make sure that this ends up adding Potato.c, not potato.c. (This might solve previous automatically.) + * More generally, users of these filesystems expect not to have to be careful about case when specifying commands. So, for instance, "monotone revert potato.c" -> "error: no such file" -- "but it's right there! stupid program". This applies to all commands that take filename arguments -- all restrictions, etc. + * Proposed solution: ? + * Ignorant Win32/Win16/DOS applications have been known to invent new filenames that differ in case from what was specified at file open time, e.g. user edits file.txt (selected via a GUI) and saves it, and the program saves it as FILE.TXT or File.txt. + +---- +IMHO, darcs got it right. Warn the user at the point that conflicting cases are being added to the repo, but allow an override. Warn regardless of platform. If the user overrides, they're on their own. That doesn't solve the problem for existing monotone repos, but it's a reasonable policy moving forward. + * Unfortunately, this cannot be done fully reliably (because "case insensitive" is ill-specified), and the above conditions still need to be handled somehow. But it would be a pleasant bit of UI sugar for users. ============================================================ --- wiki/CertCleanup.moin c47fd639b8465493a96065fe6dc36e12ea7086ef +++ wiki/CertCleanup.moin c47fd639b8465493a96065fe6dc36e12ea7086ef @@ -0,0 +1,12 @@ +While we're doing VersionedPolicy, we probably want to take the opportunity to clean up some stuff about how we do certs. + +Some thoughts: + * should we namespace certs, like we do attrs? I.e., have cert names like `mtn:branch`, `mtn:author`, etc.? + * BranchRenaming is hard, because literal branch names are tied too closely to branch certs, and changing literal cert values is hard (as noted in UsingCerts). The fix is not to allow certs to be changed, but to abstract branch names from cert values using VersionedPolicy. + * certs should have ids, like other objects -- so that we can refer to them when necessary. (This is useful for packet commands, for stating which certs should be trusted, etc.) + * perhaps make the cert format basic_io and documented? add a format version number too, while at it (though it's hard to imagine what would change about certs, them just being tuples and all). + * review how we're doing things like formatting cryptographic data to make sure that it's all up to snuff. + * possibly, add "issued by" and "date" fields. + * certs currently state the key they are signed by by referring to its key id. key ids are currently generated by hashing the actual key, plus the key's associated name. In a VersionedPolicy world, key names are no longer intrinsic properties of keys, but can be different over time (and space -- one key may exist in multiple namespaces); so perhaps these key hashes should change. + * combining date/author/changelog certs into a single cert would save a bunch of space and tie the date that someone said something together. (currently there is ambiguity on revs that have multiple date/author/changelog certs in terms of who said what, when). including branch certs into this new big cert might also be a good thing. + * change our invariants so that we simply don't store certs that we can't verify. treat keys as preconditions to accepting certs, just like we already treat revisions as preconditions to accepting certs. don't bother writing out certs that have invalid signatures -- they are essentially malformed data, like a revision without a manifest stanza or the like. this means we don't have to verify signatures at runtime -- expensive! -- but avoids adding all sorts of annoying cache consistency logic. ============================================================ --- wiki/ChadWalstrom.moin 5ae7f609607231dd8a8429ebdafd94a11448e435 +++ wiki/ChadWalstrom.moin 5ae7f609607231dd8a8429ebdafd94a11448e435 @@ -0,0 +1,8 @@ +GNU Arch refugee since monotone 0.18. + * [[MailTo(chewie AT wookimus DOT net)]] + * http://wookimus.net/~chewie + * Debian Developer [[MailTo(chewie AT debian DOT org)]] + * GNU GNATS Maintainer [[MailTo(chewie AT gnu DOT org)]] + +------- +CategoryHomepage ============================================================ --- wiki/ChangeLog.moin 7ae6cc3b924c08cbe32cd85f74aec76697ca6a29 +++ wiki/ChangeLog.moin 7ae6cc3b924c08cbe32cd85f74aec76697ca6a29 @@ -0,0 +1,153 @@ +This is a first little piece of emacs-code, to achieve the task of writing log messages to {{{_MTN/log}}} instead of {{{ChangeLog}}} if appropriate. (Note that [http://download.gna.org/dvc/ DVC] already includes a similar feature, bound to C-x V a by default.) + +Look at the source for a way to use it. From now on use {{{mtn-add-change-log-entry}}} instead of {{{add-change-log-entry}}}. {{{mtn-add-change-log-entry}}} will try do the right thing. + +If a directory named {{{_MTN}}} exists in the buffers {{{default-directory}}} or in any parent directory, use {{{_MTN/log}}}, {{{../_MTN/log}}} or whatsoever. {{{./ChangeLog}}} (or better {{{change-log-default-name}}} as from customize) otherwise. All your customisations ({{{M-x customize-group RET change-log RET}}}) work as expected. + +I have a symbolic link named {{{current}}} in my home directory, that always points the folder of the project I'm currently working on. If I {{{mtn-add-change-log-entry}}} on a file in there, these functions still search up the real directory tree. + +So if {{{/home/sebastian/current}}} points to {{{/home/sebastian/develop/gtkmm/application/src}}}, and there are {{{/home/sebastian/develop/gtkmm/_MTN}}} AND {{{/home/sebastian/_MTN}}}, {{{mtn-add-changelog-entry}}} will choose {{{/home/sebastian/develop/gtkmm/_MTN/log}}}. + +Since {{{mtn-add-change-log-entry}}} calls {{{add-change-log-entry}}} interactively, you still can choose to write to use an other file. + + + + +{{{ +;; File: sr-monotone.el +;; $Revision: 1.2 $ +;; Date: 2006-12-04 +;; Author: Sebastian Rose +;; License: GPL +;; +;; Copyright (c) 2006 Sebastian Rose +;; +;; +;; Provides to funktions: +;; * mtn-get-parent-directory (child) +;; returns the parent directory or nil, if there is no parent. +;; I wrote it, since I could not find a function like this. +;; * mtn-add-change-log-entry () +;; looks for _MTN directory and changes the behaviour of +;; add-change-log-entry to use /PATH/TO/_MTN as directory +;; and 'log' as the default filename for the logfile. +;; +;; +;; +;; Usage: +;; +;; THE ONE WAY +;; In your .emacs put this line: +;; (require 'sr-monotone) +;; ... and place this file somewhere in your load-path. +;; +;; +;; THE OTHER WAY +;; Copy the two functions here and paste them in your .emacs. +;; +;; +;; +;; Bind any key you like to mtn-add-change-log-entry. +;; (global-set-key [(f8)] 'mtn-add-change-log-entry) +;; +;; From now on only use mtn-add-change-log-entry. It detects automagically the +;; right way to call add-change-log-entry. + +(provide 'sr-monotone) + + +(defun mtn-get-parent-directory (child) + "Retruns the parent directory or nil, if there is no parent. +Parent has always a trailing slash, or what ever is your systems +file separtor. +Improvements and suggestions to address@hidden" + (if (file-regular-p child) + (file-name-as-directory (file-name-directory child)) + ; this is else: + (let ((child (file-name-as-directory child))) + (let ((dir (file-name-as-directory (expand-file-name child))) + (parent (file-truename + (file-name-as-directory (expand-file-name (concat child "..")))))) + (if (string= dir parent) + nil + parent))))) + + + +(defun mtn-add-change-log-entry() + "Searches in buffers default-directory and above for a directory +named '_MTN'. If it exists, monotone-add-change-log-entry calls +add-change-log-entry interactively with apropriate arguments. +Otherwise interactively calls add-change-log-entry the normal way. +So one can just bind this function to the keys, that call +add-change-log-entry now, and it will work just fine. + +Improvements and suggestions to address@hidden" +(interactive) + (let ((filename buffer-file-name) + (is-mtn-dir nil) + (original-default-directory default-directory) + (original-change-log-filename nil)) + (if (boundp 'change-log-default-name) + (setq original-change-log-filename change-log-default-name)) + (unwind-protect + (progn + (if filename + (progn + (catch 'done + (while (setq filename (mtn-get-parent-directory filename)) + (if (file-directory-p (concat filename "_MTN")) + (progn + (setq change-log-default-name "log") + (setq is-mtn-dir (concat filename "_MTN")) + (throw 'done 'is-mtn-dir))))) + (if is-mtn-dir + (let ((default-directory is-mtn-dir)) + (call-interactively 'add-change-log-entry)) + (call-interactively 'add-change-log-entry)) + ))) + (setq default-directory original-default-directory) + (setq change-log-default-name original-change-log-filename) + ))) + + + +;; 2006-16-12 +;; This function is the one you need, to make add-change-log-entry +;; print the path of the file you're writing the change log entry for +;; relative to the root of your project directory. +;; If change-log-default-name is "log", this function assumes the +;; file is part of a monotone project and return the files path +;; relative to "/_MTN/..", just like monotone commands would do. +;; Otherwise returns the path of the file relative to the directory, +;; where the log file lives in. +;; +;; No leading slash prepended. +;; +;; To use this function type +;; M-x customize-variable RET add-log-file-name-function RET +;; and make it point to mtn-add-log-file-name. +;; Unfortunately this function relies on log-file, which is an undocumented +;; variable in add-log.el, actually a local variabel in function +;; add-log-file-name (buffer-file log-file). +;; But I couldn't find an other way, to get the logfile, the user has +;; choosen at this point. +;; +(defun mtn-add-log-file-name(original-name) + "Return the filename printed in _MTN/log (or ChangeLog) relative to +the projects root. That is the driectory the file ChangeLog lives in, +if not a monotone project, _MTN/../ otherwise. + +Improvements and suggestions to address@hidden" + + (let ((directory (mtn-get-parent-directory log-file)) + (file (file-truename original-name))) + + (if (string= change-log-default-name "log") + ;; monotone + (let ((directory (mtn-get-parent-directory directory))) + (file-relative-name file directory)) + ;; else no monotone: + (file-relative-name file directory)))) + +}}} ============================================================ --- wiki/CherryPicking.moin 1d4f82bab5129c0293f8ceee7b6c18f0cfea9a16 +++ wiki/CherryPicking.moin 1d4f82bab5129c0293f8ceee7b6c18f0cfea9a16 @@ -0,0 +1,9 @@ +"Cherry picking" is an extension to merge that allows changes between arbitrary versions to be merged into the current version. + +Merging is an inherently heuristic process, and cherry-picking merge even more so; not all changes make sense in every context, so no implementation of cherry picking can be perfect. Nonetheless it's an option for some revision control systems that has been a TODO item for Monotone for some time (see the FAQ). + +As of monotone 0.28, there is a new `pluck` command. This command implements a lot of the primary functional components of cherry-picking: if you can see a `diff` between two revisions, then a `pluck` will apply that diff to your current workspace. This is a bit like feeding the `diff` output through an external program like patch, but `pluck` is aware of the ancestry differences, and will adjust the patch for file renames and other changes that have happened between the source revisions being plucked and the current workspace. + +This is not a full cherry-picking solution in the sense that some other VCSs use the term. In particular, the revisions being plucked are recorded in the changelog template in preparation for a later `commit`, but other than this, `pluck` operations are not recorded directly in the ancestry or otherwise in the metadata, and are therefore not recognised in any special way by later commands. This can be important when later merging or repeatedly plucking changes between branches. + +Even so, `pluck` is very useful, and more advanced developer practices are expected to evolve around it. Some examples of these practices are discussed in the DaggyFixes page. ============================================================ --- wiki/ChristofPetig.moin 307ebcf0bf77c77c1ab7fc4041ac9f44fd6ffe6e +++ wiki/ChristofPetig.moin 307ebcf0bf77c77c1ab7fc4041ac9f44fd6ffe6e @@ -0,0 +1 @@ +E-Mail: address@hidden ============================================================ --- wiki/CommitEarlyCommitOften.moin 2a5ce9d87b63b604915bf2f6d8ed5cdaf364ff9a +++ wiki/CommitEarlyCommitOften.moin 2a5ce9d87b63b604915bf2f6d8ed5cdaf364ff9a @@ -0,0 +1,12 @@ +Don't group many changes together into a single commit. Commit each logical change as a separate revision. + +Keeping changes small and simple in individual commits makes many later things easier: + + * small, atomic changes are easier to `disapprove` later. + * This makes it easier for others using `pluck` for CherryPicking only the changes they are interested in, because each can be referred to separately. + * If you separate bug fix commits from other development, it will help release management (especially if you commit them according to the DaggyFixes pattern). + * Doing frequent commits along a separate development line will also help when it comes time later to merge that development back with other work (as well as helping you go back to a previous state if some experimental changes didn't work out well). If you haven't done progressive propagates to keep the development branch in sync with the mainline during development, you can use the ZipperMerge pattern to recreate these small merges later. + +If you find yourself making several parallel changes, consider using parallel workspaces, one for each change. + +Using restrictions on the `commit` command (ie. mtn commit file_a file_b) to commit a small subset of the changes in your workspace. Check with `diff` to review what changes the restriction matches. ============================================================ --- wiki/ConflictFixupPolicy.moin 9c7e2bb32e0c20487fbe416e70a99a73c4c2e77e +++ wiki/ConflictFixupPolicy.moin 9c7e2bb32e0c20487fbe416e70a99a73c4c2e77e @@ -0,0 +1,49 @@ +This is about what we do during MergeViaWorkingDir or WorkspaceConflicts in order to turn the "insane" (technical term) roster into a "sane" one so we can actually write it out. This is not a resolution to the conflict! This is only the mechanical, least-effort repair that lets us get out to where we can take user interaction. + +There are seven kinds of conflicts that roster merge can produce: each is a subsection below. + +== node_name_conflict == + +Attach somewhere, i.e. make up a name that we know does not exist (because we checked) + +Record name in left, right + ++ left: parent name and basename + ++ right: parent name and basename + +== file_content_conflict == + +make up some content (with <<<< in) + +"add" left, right, "L"CA tempfiles + +== node_attr_conflict == + +need: key, value on left; value on right + +== orphaned_node_conflict == + +make up name, maybe in a subdir, attach it + +record old name / parent + +== rename_target_conflict == + +attach both somewhere + +want to know what the old name(s) were + +== directory_loop_conflict == + +this occurs from two directories a and b by renaming a to b/a on one side, b to a/b on the other + +attach somewhere + +== illegal_name_conflict == + +attach somewhere + +== missing_root_dir == + +create one ============================================================ --- wiki/CraigLennox.moin b3b5cd92610b50b0c40a750654f5956964cf6363 +++ wiki/CraigLennox.moin b3b5cd92610b50b0c40a750654f5956964cf6363 @@ -0,0 +1 @@ +I've been a happy user of Monotone since 0.15. ============================================================ --- wiki/CreatingBranches.moin 4604514e5fbbbac792bed9166495397a6e819735 +++ wiki/CreatingBranches.moin 4604514e5fbbbac792bed9166495397a6e819735 @@ -0,0 +1,13 @@ +If you want to create a new branch, the most intuitive way (that I've found) is to commit your changes with --branch= . + +Alternatively, you may want to create a branch on an existing codebase before you have any changes to commit. To create a branch from the current workspace's revision, use the {{{mtn cert}}} e.g. {{{ +mtn cert h: branch com.yoyodine.bunchy.testing +}}} + +You can then update to the branch: + +{{{ +mtn update --branch com.yoyodine.bunchy.testing +}}} + +Advantages of this approach are that multiple developers can update and begin working and committing to that branch straight away without having to coordinate their first commit between them. Also, I'm very forgetful, and I find that I often accidentally commit to the head - it's easy to forget that you intended to start a new branch, so making this the first step in your workflow prevents this happening. ============================================================ --- wiki/CustomCerts.moin 12f373f28321765641cd2c11b16c7b898ee63271 +++ wiki/CustomCerts.moin 12f373f28321765641cd2c11b16c7b898ee63271 @@ -0,0 +1,5 @@ +Monotone uses some common certs according to standard conventions as described in UsingCerts, but this is just a start. + +Certs are intended as an extendable way to store metadata about revisions. Some people even use them for this! Here are some interesting uses I know about: + * Xaraya uses them to track branch descriptions and status -- latest cert on a branch wins. http://mt.xaraya.com/com.xaraya.core/index.psp + * bug fixes and shipping to clients: http://article.gmane.org/gmane.comp.version-control.monotone.devel/6476 (not clear if these examples are real or made up?) ============================================================ --- wiki/CvsImport.moin 3d5dcd92ea387b33e0a7746faf25937599da0a70 +++ wiki/CvsImport.moin 3d5dcd92ea387b33e0a7746faf25937599da0a70 @@ -0,0 +1,81 @@ += Importing CVS repositories with Graph Based Algorithms = + +The cvs2svn people, mainly Michael Haggerty have come up with a new algorithm (see his [http://cvs2svn.tigris.org/servlets/ReadMsg?list=dev&msgNo=1451 mail]) for cvs2svn 2.0, which is based on [http://en.wikipedia.org/wiki/Graph_theory GraphTheory]. In the branch net.venge.monotone.cvsimport-branch-reconstruction, MarkusSchiltknecht maintains an implementation in C++, with some monotone specific modifications. + +== Overview == + +An import consists of three steps: + + * parsing the RCS files to collect all events into blobs + * split dependency cycles between those blobs + * streamline the graph, to resolve branch affiliation + * consuming the blobs in the graph to create monotone revisions + +== Parsing the RCS files == + +In a first step, the RCS files are parsed to generate file deltas and hashes. In all subsequent steps, files are only referred to by the hash, which allows us to do most CVS conversions in memory (as an example, importing the mozilla repository peaked at around 1.8 gb memory usage, last time I tried). Additionally, we also collect all cvs_events into blobs. Such cvs_events (which should probably better be called rcs_events) can be: + + * cvs_commit: the commit action for this single file + * cvs_symbol: a symbol on a specific commit + * cvs_tag: a tag for the file at the underlying symbol + * cvs_branch_start: a branchpoint or start of a branch at the underlying symbol + * cvs_branch_end: end of a branch + +According to the RCS version numbers, dependencies between those events are recorded, i.e.: + + * a commit of revision 1.2 depends on revision 1.1 + * symbol MY_TAG depends on the commit of revision 1.4, the cvs_tag for MY_TAG then depends on that symbol + +Depending on the type of these cvs_events, they are collected in blobs: cvs_commits with the same author and changelog end up in the same blob, obviously all equally named symbols also get their own blob. And based on the underlying symbol, all cvs_tag, cvs_branch_start and cvs_branch_end events are also collected in a separate blob. + +After this step, the dependency graph looks something like this one here, from the importing_cvs_small_real_repo unit test: + +[http://www.bluegap.ch/samples/importing_cvs_small_real_repo/t1.png] + + +== Splitting dependency cycles == + +In a second step, we check the graph for dependency cycles using a depth first search. Upon discovery of such a cycle, we try to find the best split point, to split one blob of that cycle into two. The simplest, and currently used method is splitting at the largest gap in time. This is repeated until no more cycles are left, we then have an acyclic graph, but not a tree - meaning there can still be cross or forward edges. + +See such a dependency cycle highlighted in red below, from the importing_cvs_cycle_splitter2 unit test. As commit 'blob A' has the largest gap in time, it's the one to get split up into two independent blobs in that sample. The example above does not have any cycles. + +[http://www.bluegap.ch/samples/importing_cvs_cycle_splitter2/t2.png] + + +== Streamlining the graph == + +To figure out in what branch a certain blob belongs to, we'd like to get a tree of branches. Additionally, as CVS - unlike monotone - cannot represent multiple heads and merges, we'd like to eliminate all cross or forward edges. We do that in various ways, ... to be described... + +A sample for such a cross or forward edge, from the small_real_repo test: + +[http://www.bluegap.ch/samples/importing_cvs_small_real_repo/t7.png] + +== Consuming the blobs == + +As we now have a tree of blobs (revisions), it's trivial to import that into monotone. See the streamlined graphs from our two example unit tests, first the simpler cycle_splitter2: + +[http://www.bluegap.ch/samples/importing_cvs_cycle_splitter2/t5.png] + +And here the small_real_repo in all its beauty: + +[http://www.bluegap.ch/samples/importing_cvs_small_real_repo/t8.png] + + +== Another Sample, from importing_cvs_cycle_splitter3 == + +Involving cycles with branch starts: + + * [http://www.bluegap.ch/samples/importing_cvs_cycle_splitter3/cvs_graph.all.1.png all the graph before modifications] + * [http://www.bluegap.ch/samples/importing_cvs_cycle_splitter3/cvs_graph.splitter.2.png all first cycle encountered] + * [http://www.bluegap.ch/samples/importing_cvs_cycle_splitter3/cvs_graph.no-weak.3.png all no more cycles, w/o weak deps] + * [http://www.bluegap.ch/samples/importing_cvs_cycle_splitter3/cvs_graph.splitter.4.png all streamlining 1] + * [http://www.bluegap.ch/samples/importing_cvs_cycle_splitter3/cvs_graph.splitter.5.png all streamlining 2] + * [http://www.bluegap.ch/samples/importing_cvs_cycle_splitter3/cvs_graph.all.6.png final graph, importable by monotone] + + +== Real World test repositories, and how they are currently failing == + +Tested with: 040f83b3bcd4c04adc7e3947d06a9ccffc223ad5 2008-05-01T14:00:49 + + * netbsd/othersrc: creating monotone revs: {{{../nvm.cbr/rcs_import.cc:5,018: invariant 'I(parent_blobs.size() == 1)' violated}}} + * openssl/openssl: cycle splitting stage: {{{../nvm.cbr/rcs_import.cc:3,598: invariant 'I(false)' violated}}} ============================================================ --- wiki/CvsSync.moin 3bc2bc0b23d7a4d9d92bd1a5ed82bf3fbf9dab0f +++ wiki/CvsSync.moin 3bc2bc0b23d7a4d9d92bd1a5ed82bf3fbf9dab0f @@ -0,0 +1 @@ +see CvsSyncHints and CvsSyn3 ============================================================ --- wiki/CvsSync3.moin 1328aa4f58d623e4d2e30e55d543ca7d4de8d980 +++ wiki/CvsSync3.moin 1328aa4f58d623e4d2e30e55d543ca7d4de8d980 @@ -0,0 +1,25 @@ += CvsSync rewrite #3 = + +This page just serves as a notepad to introduce you to the more esoteric features of cvssync3. + + - CvsSync3 uses attributes to store information about file revisions and metadata and directory metadata. Repository metadata is stored as root directory attributes. + + - CvsSync interfaces cvs and mtn via pipes + + - CvsSync (mtn_cvs) uses mtn infrastructure (ui.hh, sanity.hh, options.hh) while beeing an executable on its on + + - CvsSync includes a C++ class interface to monotone automate process ! + +Notes on discussion with Nathaniel during Monday + + - consider using certs for up-to-dateness of revisions + + - ? remove SHA1 attr, use explicit vs modified attr for takeover + + - clean up and generalize put_revision + + - consider attr only cvssync info storage by branching + + - put filename into RCS dotted version attr? (because of renaming) + + - maybe add cvs average date into a attribute, too ============================================================ --- wiki/CvsSyncHints.moin 897868caa72b02a7a63e076a795b5301e7c64196 +++ wiki/CvsSyncHints.moin 897868caa72b02a7a63e076a795b5301e7c64196 @@ -0,0 +1,34 @@ +The cvs_sync branch is an experimental facility to help users work with ["MonotoneAndCVS"] + +For the newest rewrite see CvsSync3. + +You may want to not stress cvssync to the full extent. It definitely has +problems when the time jumps (no I mean not summer vs. winter time) +because then the simplistic and easy to use map which sorts revisions by +time (to construct changesets) does not sort correctly concerning +heritage :-( . And it stresses the CVS server with the initial pull +[--since is much much nicer to the server, a full log over the project's +lifetime and constructing diffs between old revisions of a file is a +killer]. + +Try cvs_takeover (an ''unmodified'' tree saves you worries elsewhere! *) +and continue to work from there. Merging, updating, committing etc. +really work nice and the server is not charged that much this way. Most +people (including me) do not need full history. + +Also, sorry, cvssync does not handle side branches, yet. I yet failed to +find a decent command which gives me the exact branch-off-point of the +branch (revision number inspection seems the way to go). + +Oh, and -ko saves you much headache when you have to resync with the cvs +server. + +If anything goes terribly wrong the most efficient way to resync is: + * check the module with CVS out into an empty directory + * change into that directory + * monotone --db foo.db --branch foobranch cvs_takeover [foomodule] + * monotone merge + +*) cvssync inserts empty dummy files as the initial state which give a +MD5 sum error on update and also a warning if it gets to know the correct content +lateron. ============================================================ --- wiki/DagBasedRefinement.moin 37da0c8d23a1a51c371a90c8e9482baf67c8edd7 +++ wiki/DagBasedRefinement.moin 37da0c8d23a1a51c371a90c8e9482baf67c8edd7 @@ -0,0 +1,68 @@ +Originally posted at http://lists.gnu.org/archive/html/monotone-devel/2006-09/msg00124.html . +There's also a little bit of discussion at http://colabti.de/irclogger/irclogger_log/monotone?date=2006-09-08,Fri&sel=234#l464 . + +---- + +There's been some minor thought given to having a refinement scheme for +revisions (for netsync) that makes use of the DAG structure to do better +than the merkle refinement we do now. + +Merkle refinement is O(d*log n), d being the size of the difference +between the sets. It also has a problem where the subset of the revision +graph being synced needs to be agreed on beforehand. + +What I'm suggesting below I think will be be O(log n) generally, and +significantly better for the common case where any one dev only touches +a few of the graph heads. Additionally, mismatched sync sets won't cause +huge retransmissions like they do now. + +(Currently, pushing a nvm.newbranch can re-send all of nvm up to the +branch point, if a bad sync pattern (such as just the new branch) is +used. This should fix that.) + +The change in O() won't matter that much, since revision traffic is also +linear in d and is much bigger. What will probably matter more is the +better handling of bad sync patterns. + +Certs and keys will still need to use merkle refinement. However, this +should be delayed until *after* rev refinement is complete, so we know +exactly which revs we need to include certs/keys from. (specifically we +only have to ask about certs on shared revs, and we want to ask about +certs on *all* shared revs, even if they don't match the sync pattern) + +---- + +matching a pair of DAGs, specifically a pair of monotone revision graphs + +A "comparison" is: "I have rev XXX, do you also have it?" + +After every comparison: + * each side marks as shared all revs that it has that are + ancestors (inclusive) of a known-shared rev + * each side marks for send all revs that it has that are + descendants (inclusive) of a known-unshared rev + + +1) compare heads + Generally, an individual dev won't be active on all branches. + So, the client will still have many heads that were fetched + from the server. (maybe note that these are heads, so any + descendants the other side has can be immediately marked for + send) +2) compare roots (maybe) + If it is assumed that each history has several heads, then any + common roots would have likely been eliminated in (1). So check + any remaining roots before going random, as these are likely to + not be shared. +3) compare random revisions until all is known + Or maybe try to split the revision graph into N+1 equal chunks, + where N is the number of revs checked at once (checking several + at once due to round-trip latency). + +Should be about O(log n), but significantly better in the common case. + +Only ask about revs that are in your sync set, but reply for revs you +have regardless of whether they're in the sync set. + This would avoid the problem where, say, pushing a new feature + branch with a glob that *doesn't* include the base branch will + re-send large portions of the base branch. ============================================================ --- wiki/DaggyFixes.moin 58b4395f8be0f8ccee41f3c37b691082ea6df17f +++ wiki/DaggyFixes.moin 58b4395f8be0f8ccee41f3c37b691082ea6df17f @@ -0,0 +1,191 @@ +All software has bugs, and not all changes that you commit to a source tree are entirely good. +Therefore, some commits can be considered "development" (new features), and others can be considered "bugfixes" (redoing or sometimes undoing previous changes). +It can often be advantageous to separate the two: it is common practice to try and avoid mixing new code and bugfixes together in the same commit, often as a matter of project policy. This is because the fix can be important on its own, such as for applying critical bugfixes to stable releases without carrying along other unrelated changes. + +Monotone, and other similar version control tools that utilise a DAG-structured revision history, offer developers an additional option to handle fixes in a way not possible (or at least, not convenient) in other tools with more linear history structures. + +This page describes a BestPractices workflow pattern that uses the DAG structure, and the capability to easily diverge and re-merge from arbitrary past revisions, for advantage in handling fixes. It's an application of the same principles used by the ZipperMerge pattern, but for the scenario where you want to make the same change to two or more branches that must remain separate otherwise, rather than merge two branches together. + += Scenario = + +You have a project with a number of revisions and an existing graph that looks like this: {{{ + A + | + B + / \ + C D + \ / + E +}}} + +It is later discovered that revision `B` introduced a bug, and there's a series of children +`B->..->E` that have inherited the bug from `B`. (There could, of course, be many many intermediate revisions between `B` and `E`). + +In monotone, we have two useful choices for how (or, more specifically, ''where'') to '''commit''' the fix: + + * as a child of the current head, `E->F1`. + + * as a direct child of the revision that introduced the problem, `B->F2` (and then '''merge''' the two heads `E` and `F2` to produce `M`). + +Both produce a new head with the bug fixed, but they leave behind a different ancestry graph, and that difference can be important and useful. + +== Fix F1: the old way == + +The bug is fixed close to the point where development happened to be up to ''when it was found'':{{{ + A + | + B + / \ + C D + \ / + E + | + F1 +}}} + +This is the common established practice in +traditional sequential VCSs, in part because in those systems, branching and merging aren't lightweight enough to be worthwhile using for a small fix. +You might annotate the fix with some +mention of `B` in the changelog as the bad revision being backed out or fixed, but +that's usually as far as it goes. + +There's nothing really wrong with this (after all, it has worked for most software developers for a long time), but it represents a lost opportunity to use the power of monotone to full advantage. + +== Fix F2: the daggy way == + +The bug is fixed close to the point ''where it was introduced'', and then '''merge'''d back:{{{ + A + | + B --+ + / \ | + C D F2 + \ / | + E | + \ / + M +}}} + +There are good reasons to prefer this practice. This different graph structure gives you a strong and direct representation of the ''logical'' (rather than ''chronological'') relationship between bug, fix, and intermediate development: + + * You can see easily, in a tool like monotone-viz, the revisions containing + the bug: all the revisions in the parallel path(s) spanned by `B->F2->M`. + + * The fix is separated from other development as a direct part of the ancestry structure. Therefore, you can use the in-built merging tools of monotone, that understand how to work with this structure, to make sure the fix goes to other places that need it without confusion from other unrelated changes. + +This reverses the common practice of "backporting" fixes to older code (more on this below). Instead, the fix is developed against that older code, and then ported forward as part of the '''merge''' to the head. +This may also make the root cause of the error more apparent and thus easier to learn from, to avoid similar mistakes in future. + +There are some variations on this theme that may be useful to consider: + + * Where the bug introduced in `B` represents the ''entirety'' of the change `A->B`, you may want `F2` to completely undo the change. + For this specific case, monotone has the '''disapprove''' command, which will internally create a new revision with the reverse diff as a child of `B` (this command name is unfortunate, because it is ''not'' symmetrical with '''approve'''). + * In some rare cases where you want to redo `B` completely differently from scratch, you might want to '''commit''' that as a child of `A` (and sibling of `B`) instead. You will then have to resolve any conflicts between the two alternate changes when you '''merge'''. This kind of pattern is most relevant for more fundamental changes than simple fixes, perhaps where the line of later development eventually leads to the conclusion that `B` was a bad idea rather than a simple bug. This will usually involve an explicit named branch and several revisions for the parallel development path. You might even experiment with several variations before picking a winner. + * For most cases, you just want to go back to `B` and finish the original change properly. It's too late to fix the revisions that already inherited the incomplete or incorrect change, but you can '''merge''' the rest of the later development with the fix easily. + += Daggy release management = + +Many projects create release branches to track critical fixes to stable code while more active development goes on elsewhere. The important thing about a release branch, in this context, is that you want to separate fixes and development: + + * unlike a development branch, you don't intend to ever merge a release branch back with + mainline (where it would eventually pick up the fix). + + * nor do you want to introduce arbitrary new developments from mainline to a release branch, wholesale. + +Lets suppose, further to our example, that you had started a new release branch +from `D`, midway along the span containing the bug:{{{ + A + | + B -----+ + / \ | + C D F2 + \ / \ : + E R1 + : \ + R2 +}}} + +You can immediately see that your release branch `D->R1->R2` has inherited the bug, and is therefore also going to need the fix. + +Even better, because `F2` and `R2` have a common ancestor `B` (which introduced the bug), and `F2` contains ''only'' the fix for the bug, approving `F2` to that branch (and merging, as before) does ''exactly'' the right thing, producing a fixed revision `RF` on the branch:{{{ + A + | + B ------+ + / \ | + C D F2 + \ / \ : \ + E R1 | + : \ | + R2 | + \ | + RF +}}} + +Remember that monotone branch memberships are determined by certs, and branches need not be fully connected. After the '''approve''' of `F2` but before the '''merge''' that produced `RF`, the release branch contained disconnected revisions: `D->R1->R2` and `F2`. These are still multiple heads of the branch, and a '''merge''' can succeed because of the common ancestor `B` even though `B` is not a member of the branch. + +This represents the true place of the fix in the graph and in both branches, without +introducing any of the other changes added in `C`, `E`, or any other point past `D` where the branch diverged. +If we had committed the fix the old way as `F1` instead, and tried to use '''approve''' like this, merging the release branch would pull in all the changes from `B` to `E` as well, just like a full '''propagate''' would. + +Although not drawn here, you can just as readily see that any other branches which diverged above `B` don't need a fix, because the bug was introduced later. +If some of those were development branches that had '''propagate'''d from mainline to them, and some of those '''propagate'''s included `B`, then those branches would also need the fix. +This knowledge is the benefit of identifying `B` as the source of the bug, which you might have needed to do anyway regardless of where the fix was applied. +Making sure to apply the daggy fix at `F2` means that you automatically get the same benefit for knowledge of what has also inherited the fix. + +In general, any revision with `B` as an ancestor and without `F2` as an ancestor, has inherited the bug but not the fix. + +Remember that in distributed development with monotone, we might not yet have learned about revisions descended from `B`; in fact we might ''never'' learn of someone else's private branch derived from somewhere below B. We still want to publish the fix close to `B` so that they can then '''approve''' `F2` for their private branch and inherit the fix as well as the bug. + +If you were to add a new test and testresult cert along with the fix in `F2`, it becomes even +clearer where your fix has gone - especially if your tool can colour the +graph according to this ancestry or the testresult. + += Plucking and CherryPicking = + +In many projects, the need to apply fixes to older revisions (especially releases) is addressed by applying patches containing the fix, sometimes adjusting or backporting for the older code. +These fixes are taken from individual changes mixed with development along the mainline, and need to be separated out. +This is often called CherryPicking, and is a frequent feature request for monotone. +It's clear that many such requests are motivated by these kinds of concerns, especially from developers accustomed to these practices and familiar with support for similar features in other tools. + +Monotone now has a new command, '''pluck''', that can be used to pull the set of changes between two (arbitrary) revisions "over there" into the current workspace, taking into consideration other changes (like file renames) that have happened between "there" and "here". +This allows isolated changes to jump across parts of the revision graph, without making full ancestry connections in the same way that '''propagate''' and similar commands would. + +Doing Daggy fixes, as outlined above, will minimise the need to cherry-pick fixes instead. Daggy fixes mean using rather than losing the true origin and relationship between bugs and fixes in the ancestry graph. +However, it's worth looking at some valid and recommended uses for this functionality, even in a project using Daggy Fixes. + +== Plucking and backporting fixes == + +Doing daggy fixes all the time isn't for everyone. It's not always so easy to develop a fix directly against the revision where the bug was introduced. Perhaps the bug wasn't discovered until some other more recent code used it in ways that exposed the bug; it would be hard to debug and find the fix without this other code around. Or perhaps the importance or scope of the fix simply hadn't been realised at the time. + +So, continuing our scenario, assume the fix had been '''commit'''ted directly as a new head, `E->F1`, as in the first example. + +Now, we've found that the bug originated in `B`, and realised that the fix will be needed on the release branch as well. +Or perhaps the bug was also found on the release branch, and traced back to the common ancestor `B` from there. +Either way, we can use the new '''pluck''' command to help us. Once again, we have a couple of useful choices about where to '''commit''' the '''pluck'''ed change: + + * we could '''pluck''' the `F1` change straight across to the release branch, producing `R2->RF` as a simple fix '''commit''', much like was done on the mainline head, with none of the structural benefits of daggy fixes. + + * or, now that we know better, it might be nice to go back up to `B` and + create the 'proper' daggy fix `F2`, gaining the advantages outlined above for any other branches and descendants of `B`. + +Creating `F2` is easy with '''pluck''': {{{ + $ mtn co ... -r B . + $ mtn pluck -r E -r F1 + $ mtn commit +}}} + +For simple fixes, this new `F2` will '''merge''' cleanly with `F1` on mainline, and with `R2` on the release branch as before. + +For more intricate fixes, this step corresponds to backporting the fix from mainline to the point of origin of the bug. +This makes it easier to '''approve''' and then '''merge''' that base fix forward to other branches (which may have diverged since) as a separate change, rather than attempting to adjust the change for both development paths in the one step. + +== Plucking development == + +Attractive new features are developed on the mainline, and sometimes it's desirable to add these new features to a stable branch, once it's clear they are good. +However, we only want to bring the specific changes related to this feature onto the release branch, and not all of the other unrelated changes that would be carried along with it if we did a '''propagate'''. +If you can identify the list of changes that correspond to the feature, you can '''checkout''' a workspace on the stable branch, and '''pluck''' each of these changes into it before committing. However, doing so carries with it the responsibility to ensure that you find ''all'' of the relevant changes -- including future changes that fix bugs in the code you just '''pluck'''ed. Because you've bypassed recording the full origin of the changes in the DAG history, daggy fixes won't work: you have to '''pluck''' fixes for '''pluck'''ed features. Even then, daggy fixes are preferred: at least they're easier to see because they're kept near the source revisions the features were originally '''pluck'''ed from. + +Another example is where you've done a whole pile of development in a +private branch, but for one reason or another you really can't or don't +see the need to publish the whole gory history and internal working details for a +push into a more public repository. +You '''pluck''' the entire span of the private development branch onto the mainline, producing a single summarised change that rolls up all the intermediate work and rework and rerework, showing only the consolidated result. ============================================================ --- wiki/DatabaseCompaction.moin 9f155aac55327094cc95a4eabfa168705e47aefc +++ wiki/DatabaseCompaction.moin 9f155aac55327094cc95a4eabfa168705e47aefc @@ -0,0 +1,46 @@ +We do a pretty good job of storing the file data compactly on disk, but we should do a better job of storing metadata compactly too. Here are some ways we could do that, in ascending order of invasiveness / controversiality: + +== Compact heights == + +Heights are stored on disk as arrays of four-byte integers. As almost all entries in these arrays are small numbers, a variable-length representation would be a win, especially if it preserves the property of being able to use `memcmp` to compare them. I am 90% sure that a concatenated sequence of integers in the SQLite variable-length integer representation has this property. A sequence of ULEB128 integers does not, because ULEB128 encoded values are little-endian. This change can be totally invisible outside `rev_height.*`. + +== Put heights in the revisions table == + +I'm not sure whether this is a good idea. There is exactly one height for every revision, so storing all the heights in the revisions table would be a correct thing, and would probably take less space on disk. However, there are situations where we have to throw away all the heights and rebuild them (notably, with PartialPull, horizon moves). It may be more efficient to keep them in a separate table so we can do `DELETE FROM heights; ` rather than `UPDATE revisions SET height=NULL; `. Also, not every revision lookup needs to see the height, so we may get better disk cache behavior from keeping the heights on the side. This change would be invisible outside `database.cc`. + +== Use revision rowids in the revision_ancestry table == + +The revision_ancestry table's schema currently reads like so: + +{{{ + CREATE TABLE revision_ancestry + ( + parent not null, -- joins with revisions.id + child not null, -- joins with revisions.id + unique(parent, child) + ); +}}} + +where ''parent'' and ''child'' are both SHA1 values stored as binary strings, joining (as it says) with the "id" field of the revisions table. We could instead turn them into `INTEGER`s and have them join with sqlite's internal `ROWID`s. This change could be confined to database.cc at the price of having to join this table against `revisions` on every access, or else we could make a globally-pervasive change that ceases to use the SHA1 binary strings as cookies for revisions internally (using the `ROWID`s instead). This would make more sense if we also ... + +== Use revision rowids in other tables that join with revisions.id == + +This concept can also be applied to the tables `heights`, `rosters`, `roster_deltas`, and `revision_certs`. Note that the IDs stored in `rosters.id` and `roster_deltas.id` are actually the associated ''revision'' hashes. + +== Use rowids for all foreign keys == + +Other columns that are joined-with (at least notionally; we don't use sql joins much) and contain SHA1s are `files.id`/`file_deltas.id` (`file_deltas.base`) and `public_keys.id` (`revision_certs.keypair`). + +== Put all the SHA1s in a lookaside table == + +At present just about every SHA1 value we have is stored at least twice, once as the actual hash of some blob, and one or more times as a pointer in some other data structure. We could put them all in a lookaside table, and use the `ROWID` in that table everywhere they appear now. We could then turn all the fields that point into that table into `INTEGER PRIMARY KEY`s and have SQLite collapse them into the `ROWID`. (This is basically an extra fillip on "Use rowids for all foreign keys" above.) + += More radical changes = + +== Compact revision/roster format == + +Define a new on-disk format for revisions/rosters which is not textual and can be stored/queried more efficiently? + +== Experiment with other compression algorithms == + +bzip2, p7zip, lzma... ============================================================ --- wiki/DatabaseLocking.moin 10a3ab523a33216b9943e9113308a30bbbc364be +++ wiki/DatabaseLocking.moin 10a3ab523a33216b9943e9113308a30bbbc364be @@ -0,0 +1,26 @@ +''(source discussion: http://colabti.de/irclogger/irclogger_log/monotone?date=2005-12-08,Thu&sel=90#l151)'' + +Discussion of database locking in Monotone, problems and suggested solutions. + +When monotone code needs to start a transaction, it instansiates "transaction_guard". By default this leads to execution of the SQL statement "BEGIN EXCLUSIVE". Transaction guards can also be created in a non-exclusive mode; in this case "BEGIN DEFERRED" is run. This should only be done if it is believed no database writes will be performed. + +We are trying to monotone bailing when a transaction involving writes is committed. "BEGIN EXCLUSIVE" guarantees that monotone will exit early and with a sensible error if unable to gain a write lock on the database. However, it has the major disadavantage that readers are excluded from the database for the entire time the command is running. + +Sqlite3 has several levels of locking. Some discussion has occurred of switching to "BEGIN IMMEDIATE" rather than "BEGIN EXLUSIVE"; only one process can hold an IMMEDIATE lock but SHARED (reader) access is still permitted. At the time of commit, IMMEDIATE transitions to PENDING (no new readers) to EXCLUSIVE. The amount of time readers are unable to access the DB is reduced, however we still encounter the crash if there is a reader in the db (see use case from NJS below). + +Sqlite does save us from "dirty" reads; a dirty read is seeing uncommitted writes in another transaction. + += Use cases = + + * (from njs) e.g., "monotone diff | less monotone commit" -> crash, db is locked + * ViewMTN calls monotone a lot, only to do reads. It can't access the db when the database is being updated with "monotone pull". + += Ways forward = + +15:22 <@njs> "In the current implementation, the RESERVED lock is also released, but that is not essential. Future versions of SQLite might provide a "CHECKPOINT" SQL command that will commit all changes made so far within a transaction but retain the RESERVED lock so that additional changes can be made without given any other process an opportunity to write." +15:22 <@njs> ^^ sounds like what we've been wanting... + +Reference: + * http://www.sqlite.org/lang_transaction.html + * http://www.sqlite.org/lockingv3.html + * http://www.postgresql.org/docs/8.1/static/transaction-iso.html ============================================================ --- wiki/DeltaStorageStrategies/DeltaStorageStrategies%2FShootOut.moin dd0b0d51efc27bc72c6825e27875ef28f83428ad +++ wiki/DeltaStorageStrategies/DeltaStorageStrategies%2FShootOut.moin dd0b0d51efc27bc72c6825e27875ef28f83428ad @@ -0,0 +1,64 @@ +|| ''When the going gets tough, the tough get empirical.'' || + + +So, we have a few prototypes, now what? How do we choose? + += candidates = + +All candidates should run with blob support and appropriate block size, since these could potentially have non-linear effects. + + * current mainline (baseline for comparison) + * against-base + * linear forward chaining + * linear forward chaining with skips or breaks + * classic [http://www.selenic.com/mercurial/wiki/index.cgi/Design#head-ef542bce2b68f24d275e7908636317491f678648 revlogs] ("classic" in that cmason is doing [http://thread.gmane.org/gmane.comp.version-control.mercurial.devel/5407 a bunch of playing around] with different sorts of revlogs right now too; not in the sense that we use ''exactly'' this design, since for the prototype at least we're doing a few tricks differently) + +A big question is how much tuning should be done on these. The goal is to get an idea of how the technique would perform in a "proper implementation", but without spending ages of time super-optimizing each possibility before we even know if it's worth it or not. So we should do the things that would seem to make a qualitative difference. E.g., it's probably worth making sure that netsync is smart enough to avoid reconstructing versions when actually unnecessary. + +A big question: is it worth implementing the lookup-chains-by-rowid optimizations that drh suggested for these tests? In principle they should not affect locality _much_, since we are not VACUUMing, but avoiding traversing indexes should be a win of some magnitude. + * When profiling checkouts and pulls there doesn't seem to be a significantly amount of (wait-)time spent in things that look index-related for sqlite (An exception is when the database hasn't been ANALYZEd recently). It's possible that I'm not looking at the right callstacks though. - Matt Johnston + += testing methodology = + +We should test both full pulls, and repeated incremental pulls, since the various methods may interact in complicated ways with repeated incremental pulls. (These can screw up disk locality in various ways, cause non-optimal ordering for forced delta linearization like classic revlogs do, etc.) + +So, for each test dataset, we have a single db. Call this PRISTINE-0. >From this, we use `db kill_rev_locally` repeatedly to produce smaller and smaller dbs, PRISTINE-1, PRISTINE-2, PRISTINE-3, etc. PRISTINE-''n+1'' is produced by taking PRISTINE-''n'', and repeatedly running `automate leaves`, picking a random item, and `db kill_rev_locally` on it. I'm not sure how many revs we should remove each time, or how many of these sets we should generate. Note that the randomness here impacts reproducibility; either save these databases so everyone can re-run the tests using the same dbs, or specify the random seed used. + +Up until this point, everything can be done with just a random mainline version of monotone. + +Now, for each ''n'', serve up PRISTINE-''n'' using mainline, and pull it into a fresh db using the version under test. Call the result TEST-''n''. These are the databases we will actually use for testing. + +Now, measure the following things: + * pulling TEST-0 into a fresh database. Measure server CPU time, client CPU and real time, and bytes transferred. Measure size of resulting db (both `du` and `du -a`, for the revlog case), and time for a cold-cache checkout, and time for a hot-cache checkout. And time for a cold cache `log --diffs --last=20`, and same on hot cache. (To do a cold-cache checkout on linux, put the database into a separate partition, then umount that partition, re-mount it, and immediately run a checkout from it.) + * pulling each of the TEST-''n'' databases into a single database -- to simulate a user tracking a project by doing a daily incremental pull. Measure the size of the resulting db (`du` and `du -a` again), and time for a cold-cache checkout, and time for a hot-cache checkout, and hot and cold `log --diffs --last=20`. (Maybe measure the time each pull takes too?) Finally, measure the server CPU time, client CPU and real time, for doing a fresh pull ''from'' the incrementally pulled database. (This simulates the db a server would generally have, produced by incremental pushes.) + += data sets = + +Some interesting ones: + * `net.venge.monotone*` + * `net.venge.monotone* --exclude net.venge.monotone.contrib*` + * xaraya core, modules, themes, languages -- http://mt.xaraya.com/ (many checkins, not so large a tree, I think) + * openembedded -- http://ewi546.ewi.utwente.nl/OE/OE.db.bz2 (large tree, fair number of checkins) + * CTWM -- http://ctwm.free.lp.se/monotone-crash-course.html (tiny all around) + * something big in both tree and history... anyone got a kernel import around to play with? + += questions = + + * is the above candidate set appropriate? are we confident these are the interesting contenders? + * "skips or breaks" -- which should we do? both? what is actually implemented? + * is there anything else we should measure? time to restore some arbitrary older stuff or something? + * it might be worth timing "log (--diffs)" or similar operations that don't just operate on a single revision? + * do we have working versions of all of the candidates? + * do we have a kernel-ish history available to test scalability on? + * who will do this work? individual tasks: + * make sure each candidate works + * '''msh'''?: forward chaining and against-base + * '''graydon'''?: revlogs + * '''?''': make sure netsync is smart about letting the db do the work + * '''?''': write the scripts to actually run a monotone on one of these data sets, i.e. implement the methodology section + * au.asn.ucc.matt.monotone.shootout has a "mkpristine.py" script for creating PRISTINE-N dbs. + * '''?''': procure a big scalability data set, like get a kernel import or something. cvs_import isn't so good for this, because we want realistic branching... maybe the bk import tool someone posted to the list recently would be useful, or porting git_import to rosters (shouldn't be too hard)... + * '''?''': actually get all of the different configurations together and run the tests on a single machine. This might actually be several people, just to make sure that things don't vary wildly between OSes (e.g., OS X has surprised us in the past). + * '''njs''': organize all of the above, point of contact for figuring out what to do next and keeping track of who knows what + +It is more important to get some numbers than to get perfect numbers, so probably the most important thing is to get the script working, and then to get the candidates basically working, and the last priority is getting super-good data sets. ============================================================ --- wiki/DeltaStorageStrategies.moin bd9cbd626092970d68005364aff90008380ecac4 +++ wiki/DeltaStorageStrategies.moin bd9cbd626092970d68005364aff90008380ecac4 @@ -0,0 +1,79 @@ +Here are some of the known ways one ''could'' potentially do delta-compression on large version corpora. + + * backwards linear-chained deltas (like classical monotone) + * backwards linear-chained deltas with occasional full-text breaks + * forwards linear-chained deltas + * forwards linear-chained deltas with occasional full-text breaks + * forwards deterministic skip-deltas (like svn) + * forwards/backwards randomized skip-deltas (like classical skip-lists) + * single base plus many deltas against it -- i.e., store a->b->c->d as (a, a->b, a->c, a->d), creating a new base as deltas grow. these pretty much have to be forwards deltas. (D. Richard Hipp, "XDFS-f" in [http://xmailserver.org/xdfs.pdf Josh MacDonald's masters thesis] (who cites Burns and Long)) + * whatever it is git uses to find similar items -- sorting by size or something? + * tree-structured storage -- using the inexplicably-not-well-known trick for storing strings as trees, one can share subtrees. Josh cites EXODUS and SDS2 (see 2.2 of the thesis) as using this trick, and there are some other interesting cites in the same section. + * several of these mechanisms can be applied either to a forced-linear history (like hg uses), or allowing forks (and merges?) to appear in the reconstruction graph. Josh actually claims that that forced-linear time ordering gave him smaller deltas than RCS-style-topology branched deltas, on his test case (FreeBSD CVS history -- I guess they must have a lot of bug-fixes applied to multiple branches or the like?). + * weaves (actually, these should maybe be thought of a sub-case of tree-structured storage -- with a different perspective) -- as traditionally implemented, I think these get ''excellent'' compression, because you have to rewrite your whole weave on every change, so you might as well compress the whole thing at once, and that gives your compressor much more to work with than a delta-chaining approach. (Unless you batch up your deltas somehow.) + += Random thoughts = + +xdelta actually supports multiple-source deltas totally straightforwardly -- basically you just use all the sources as potential places to draw strings out of in COPY operations. is this useful at all? + +Josh also reminds us that it's possible to use extent-style tricks to efficiently combine (and maybe even invert?) delta chains, which can be useful if you have some deltas on disk and you want some different deltas to send over the network or whatever. + +[http://www.almaden.ibm.com/projects/data/storagesystems/iopads97.pdf Efficient Distributed Backup with Delta Compression (Burns & Long, 1997)] has some analysis of forward vs reverse vs against-base delta performance. + +Chaining, skip-deltas, and against-base all seem to be special cases of some more general family of algorithms -- they're all trying to pick some rule that will balance compression against reconstruction cost. Surely none of these particular three points are at the global optimum of the fitness function for this class? And I observe that the competing variables we want to optimize for are simple to measure as we go on the actual data we're trying to store... (i.e., we can in principle calculate how many seeks, how many bytes, etc., we are using, and make decisions based on that.) + += Interaction with netsync = + +Netsync wants to send simple forward linear-chained deltas. Reconstructing other things from these can be very expensive (e.g., what we do now to get backward linear-chained deltas, where we not only reverse every delta, but we store each full version to the db and then remove it again when the next delta comes in!). Against base deltas might be doable here (when considering the compression mentioned below), though making sure the other side has the base adds some amount of complexity, and I'm not sure how well this works when the receiving side ''does'' have some files already. + +Netsync also wants to send exactly what is in the source's db, to minimize load on servers. + +== Forward versus Reverse Linear Chains == + +The advantage of reverse linear chains seems to be that the most common accesses (check-outs) +are against the end of the chain which in a reverse linear chain means there are no deltas to +apply. But a reverse linear chain makes netsync difficult. A forward linear chain would +help out netsync, but it has the disadvantage that you have to follow the whole chain of +deltas from beginning to end in order to get the latest version. + +Perhaps one can meet both needs by keeping a forward linear chain +but also keeping a cache of fulltext of the N most recently accessed files. Or perhaps +the cache just contains a copy of the end of each chain. In this way, netsync gets +the benefit of a forward chain and check-outs can usually be fulfilled from +cache and thus avoid the long delta chains. + +== Interaction with zlib compression == + +To counteract increased netsync traffic using against-base deltas, applying zlib to the entire stream (rather than per-packet) seems to make against-base deltas comparable to linear deltas. (I think this requires the assumption that we send related deltas together at netsync time, i.e. sort by file.) + +See the au.asn.ucc.matt.monotone.test-deltas branch in the main venge.net repository for a test script and [http://matt.ucc.asn.au/monotone/delta-screenshot.txt sample output]. + +== Size comparison for against-base deltas == + +For the initial net.venge.monotone* database, of size 90,074,112: (all sizes are vacuumed) +Storing full files when size(del(base,new)) > N*size(base): +{{{ +N=0.10: 152,059,904 +N=0.15: 171,443,200 +N=0.20: 183,305,216 +N=0.30: 213,744,640 +}}} +So this is fairly consistent with drh's experiments, with a ~1.5x-2x size increase. Cold-cache checkout times for head are slightly shorter with the normal reverse-chained-delta database (though may be experimental error). + +== Revlog variations == + +http://thread.gmane.org/gmane.comp.version-control.mercurial.devel/5407 + +It looks like the mercurial guys are very seriously considering switching to delta-against-parent in some situations, because it seems to give significant space savings: + http://www.selenic.com/pipermail/mercurial/2006-March/006910.html +(Apparently size may matter more than pure seeks for cold cache; and there are some interesting tweaks going on, like only doing this for files, not for their roster equivalents.) + +http://thread.gmane.org/gmane.comp.version-control.mercurial.devel/5862 + += Random thought on space locality using current sqlite functionality = + +Store a whole revlog-style whole-base+deltas span (a revlog actually consists of many of these spans, but you tend to access them sort of independently) in a single sqlite row. In an ideal world, sqlite would let us read/write from such rows directly (possibly without allowing us to change their size), and we could store all deltas in such thingies. Maybe even mmap them. In this world, we would probably have to keep the latest deltas split up into separate rows like now, but could archive old ones into more compact and seek-friendly storage this way. (I am only assuming that if we allocate a whole large blob at once, it will end up contiguous on disk.) + += Shootout = + +How do we choose? DeltaStorageStrategies/ShootOut ============================================================ --- wiki/DerekScherger.moin f22501976e4e878a786edf6221944d2527a69234 +++ wiki/DerekScherger.moin f22501976e4e878a786edf6221944d2527a69234 @@ -0,0 +1,9 @@ +#format wiki +#language en +== Your Name == + +Email: [[MailTo(address@hidden)]] [[BR]] +IRC nick: dscherger + +---- +CategoryHomepage ============================================================ --- wiki/DevGroup.moin 3e26e8355833e3b04744c6b893e6c98dcee3edec +++ wiki/DevGroup.moin 3e26e8355833e3b04744c6b893e6c98dcee3edec @@ -0,0 +1,8 @@ +#acl DevGroup:admin,read,write All:read + +Anyone listed on this page can edit this page. Anyone listed on this page is automatically given admin rights on this wiki, and in particular the ability to protect/unprotect pages from editing, and delete nonsense pages. Anyone listed on this page should feel free to add other people that should be listed on it, if you're missing I probably just didn't know the wikiname to use... + * JustinPatrin + * MattJohnston + * NathanielSmith + * ThomasMoschny + * ThomasKeller ============================================================ --- wiki/DifferentDbsForServeAndWork.moin 2839715a5aee64481fe929af6def244514139fea +++ wiki/DifferentDbsForServeAndWork.moin 2839715a5aee64481fe929af6def244514139fea @@ -0,0 +1,5 @@ +At some point you'll want to share your work with others, and set up a sync server. You can run a 'mtn serve' off of the same database that you check all of your changes into. This will work, but it has problems: + + * when you are working, and commiting code, monotone locks the database. The monotone server then can't serve anything anymore. + +It is better to have a separate database to run monotone serve off of, and sync to it locally from your working database. ============================================================ --- wiki/DocTodo.moin ea5b07eec1ba0b917ac4fbeb334a6f336230205e +++ wiki/DocTodo.moin ea5b07eec1ba0b917ac4fbeb334a6f336230205e @@ -0,0 +1,40 @@ +Some tasks for improvements to documents: + += problems = + + * reference docs for automate commands actually document the different tokens that can appear + * automate.cc duplicates this reference stuff in comments + += user documentation = + + * improve the getting started entry points, perhaps into several different documents with stories told from different perspectives: + + * a quick worked-through example, with commands and output and very brief comments (links to more details) for a quick overview + * someone getting started on a new, blank project (like juicebot) + * someone pulling down an existing monotone-hosted project (like monotone's [http://venge.net/monotone/self-hosting.html self-hosting] page; even a template for other projects to stick on their sites to help get users started, with links back to monotone doc for more details) + * someone looking to migrate an existing project from other-VCS to monotone + * someone looking to use multiple VCS's in parallel, perhaps while trialling them, via .cvssync or tailor + * source-code tour (see http://opensolaris.org/os/community/zfs/source/ for a good example in another project) + * ... ? + * A good writeup of similar ideas: http://headrush.typepad.com/creating_passionate_users/2006/09/how_to_get_user.html + + * a "usage guide" document (or set of wiki pages, even) on common patterns, BestPractices, TipsTricksScripts, etc + * why you should commit before update, why you should pull and merge before pushing, etc + * a good description of how to use branching and propagate; see savannah #6523 and possibly using the BranchAnalogy + * njs (in particular) is constantly coming out with cool little shell snippets using "monotone list ..." and "monotone automate ..." commands. + + * generate the man page from commands.cc's metadata. (maybe simplest just to add a monotone command that dumps out some troff or something; run it during build.) + += advanced / internals documentation = + + * formally document the basic_io format, and its intentions and usages. a lot of the automate commmands will emit or consume this format, and an understanding of the precepts will be vital for advanced users and authors of additional tools using monotone. + * see http://lists.gnu.org/archive/html/monotone-devel/2005-10/msg00033.html for a beginning + * see BasicIoFormalisation for some details and debate + * a definition of the whitespace normalisation that goes on + * a reference for the entitities that can be emitted (data type dictionary), either as a list or as a component of each command description + * see http://colabti.de/irclogger/irclogger_log/monotone?date=2005-11-25,Fri&sel=117#l194 for some more discussion + + * netsync theory and operational model (less so the specific bitwise wire protocol) + * how merging really works, and how to get specific results and fine-grained control over it, for advanced users + * document and draw rosters + * document the merge algorithm we use (straight-forward adaptation of the [http://article.gmane.org/gmane.comp.version-control.revctrl/93 multi-*-merge paper] gives a start, plus things like lifecycle, attrs, etc.) -- very useful for advanced users, too. ============================================================ --- wiki/EmileSnyder.moin 2e482b3b818313e543baa791c73e927930004ba7 +++ wiki/EmileSnyder.moin 2e482b3b818313e543baa791c73e927930004ba7 @@ -0,0 +1,11 @@ +#format wiki +#language en +== Emile Snyder == + +Email: [[MailTo(address@hidden)]] [[BR]] +IRC nick: esnyder + +... + +---- +CategoryHomepage ============================================================ --- wiki/EssentialMonotone.moin f1ecd084a3c201cb3ff9fdc9208b24bf5b1c709a +++ wiki/EssentialMonotone.moin f1ecd084a3c201cb3ff9fdc9208b24bf5b1c709a @@ -0,0 +1,39 @@ +What is the bare minimum command set needed to use monotone? + +For read-only/"anonymous" tracking of an existing project: + + Initial setup: + + `mtn pull --new-db --db `''project''`.mtn `''host'' ''branch*wildcard'': do an initial fetch + + `mtn checkout -b `''branch'' ''directory'': check out latest source + + Updating: + + `mtn pull && monotone up`: pull latest source and update working copy + + See [http://venge.net/monotone/self-hosting.html Self Hosting] for further details on doing this for monotone itself. + +For contributing: + + Initial setup: + + `mtn genkey` ''address@hidden'': introduce yourself to monotone (only run this once ever, then copy around the file ~/.monotone/keys/''address@hidden'') + + `mtn pull --new-db --db `''project''`.mtn `''host'' ''branch*wildcard*'': do an initial fetch + + `mtn checkout -b `''branch'' ''directory'': check out latest source + + Commiting: + + `mtn commit` + + Publishing: + + `mtn sync` + + Merging: + + `mtn merge`, `mtn propagate` + +(FIXME: fold this into the manual) ============================================================ --- wiki/EvaluationFeatures.moin 1487779e18771c1e42562df66fa3522a188e5d1d +++ wiki/EvaluationFeatures.moin 1487779e18771c1e42562df66fa3522a188e5d1d @@ -0,0 +1,37 @@ +There has been a great deal of VCS development activity in recent years, with many projects and many different solutions to the version control problem -- with significant similarities and differences between them. + +For developers frustrated with their current tools (often CVS, but also others) and looking for an alternative to migrate to or start using with new projects, this can be a confusing and rapidly changing landscape. Some public comparisons have been done, each with specific objectives and each at a point in time. + +This is a collection of links to pages that describe monotone's capabilities and limitations in a fashion that may be useful to those trying to compare monotone to some of the alternatives. These pages attempt to give monotone-specific answers and descriptions of features, indexed and with reference to terminology and requirements raised elsewhere. It is hoped that this will help a consistent and more accurate comparison. + +While we happen to think monotone is already really good and getting better all the time, we also recognise that it is not perfect, not yet finished, and not for everyone. We'll be honest about our limitations, and describe how we intend to address them in future work. We won't try to be all things to all users, but if you're looking for a feature you don't find described here, please let us know. + +''Note: this list is under active construction, there are several more pages yet to be written for this list. The first entries on this list are based heavily on the requirements and features from [http://wikitest.freebsd.org/VersionControl FreeBSD's evaluation], and they're still underway though mostly done at this point. We will add references to other collections as time goes on.'' + + * FeatureAccessControl + * FeatureAtomicCommit + * FeatureBuildIntegration + * FeatureCommitMail + * FeatureCompactRepository + * ["FeatureCVSExport"] + * ["FeatureCVSImport"] + * ["FeatureEmbeddedIDs"] + * FeatureFast + * FeatureLightweightBranches + * FeatureLogReview + * FeatureLogTemplates + * ["FeatureMIMEtypes"] + * FeatureMerging + * FeatureMirroring + * FeatureNetworkSecurity + * FeatureObliterate + * FeatureOffline + * FeaturePortable + * FeatureRename + * FeatureRobustRepository + * FeatureSignedRevisions + * FeatureSymlinks + * FeatureVendorBranches + * FeatureWebInterface + +or add a new one based on the FeatureTemplate ============================================================ --- wiki/FAQ.moin ec9e4100d5748efeaf38465f096c03ab5fb73db6 +++ wiki/FAQ.moin ec9e4100d5748efeaf38465f096c03ab5fb73db6 @@ -0,0 +1,112 @@ += Where should I go to ask more questions? = + * on IRC: irc.oftc.net #monotone + * via email: http://mail.nongnu.org/mailman/listinfo/monotone-devel + += What are these libraries monotone depends on? = +[http://www.boost.org/ Boost] + A set of general-purpose C++ libraries with lots of features. I use it for string processing (regexps, parsing), sockets, portable filename handling, and more. It's superb. Currently, that's all; and it is possible (and easy) to statically link against Boost, to create a binary usable on a system with no external libraries at all. + += Why did you use SHA1 as your hash algorithm? = + * It's a secure hash: nobody can look at a cert on some SHA1 hash code and cook up a fake file with the same hash code (hijacking the cert) in any reasonable amount of time. + * Of the secure hashes, it's among the most well known. + * Of the well-known secure hashes, it's the one with the least number of rumors circulating about it having been broken; md4 is supposedly dead meat, and md5 has (some) people worried. + * The speed problem -- SHA1 is a bit slow -- seems mostly overwhelmed by I/O and the time spent in RSA. The benchmark on SHA1 shows it doing over 40mb / sec on a celeron. It should be fast enough. + += But what about the rumors that SHA1 is broken? = +There are indeed such [http://www.schneier.com/blog/archives/2005/02/sha1_broken.html rumors]. We're watching closely, and if this is confirmed, we'll wait until the cryptographic community settles on a replacement, and switch to using that. We know how to do the switch, and it should be straightforward. + +In the mean time, we can wait until consensus emerges before making the switch. The reported attacks are still extremely costly (it remains much, much easier to break into your computer and steal your key), and there are many, many applications just as vulnerable and far more interesting to attack (e.g., SSL host certificates, PGP keys, etc.). We'll fix it, when we can be confident that our fix is correct. + += How do you merge versions? = +The merging system is based on a pair of 3-way merges: one set-oriented one at the changeset level to resolve differences in tree layout (file and directory renames, for instance), and one line-oriented one at the file level, to resolve differences in concurrent edits to the same file. If either of these fail, they are passed off to a user-provided hook function, which invokes emacs ediff mode by default (but can be overridden). + +It is important to note that a 3-way merge is not the same as simply "applying patches" in one order or another: we locate the least common ancestor of the merged children in our ancestry graph, calculate the edits on the left and right edges, adjust the right edge's edit coordinates based on the left edge's edits, and only ''then'' do we concatenate the left and right edges (ignoring identical changes, and rejecting conflicting ones). + += Monotone wants me to use a merge tool; what do you recommend? = +The best we know for merging is [http://furius.ca/xxdiff/ xxdiff]. Just install it, and monotone will automatically default to using it for merges. + += Isn't it annoying that xxdiff doesn't have any keybinding for "save as merged"? = +`echo 'Accel.SaveAsMerged: "Ctrl+M"' >>~/.xxdiffrc` + += What is the "networking protocol"? = +The networking protocol is called `netsync`. It is a bi-directional pipelined protocol for synchronizing collections using a tree of hashed indices. It allows any copy of monotone to function as either a client or a server, and rapidly synchronize or half-synchronize (push / pull) their database with another user. It is somewhat similar in flavor to [http://samba.anu.edu.au/rsync/ rsync] or [http://www.cis.upenn.edu/~bcpierce/unison/ Unison], in that it quickly and idempotently synchronizes information across the network without needing to store any local state; however, it is much ''more'' efficient than these protocols. + +An important fact about monotone's networking is that it deals in ''facts'' rather than ''operations''. Networking simply ''informs'' the other party of some facts, and receives some facts from the other party. The netsync protocol determines which facts to send, based on an interactive analysis of "what is missing" on each end. No obligations, transactions, or commitments are made during networking. For all non-networking functions, monotone decides what to do by interpreting the ''facts'' it has on hand, rather than having specific conversations with other programs. Only the `push`, `pull`, `sync` and `serve` commands exchange data with anyone else on the network. The rest of the time, monotone is "offline". + += What happened to HTTP, NNTP, SMTP? = +Monotone used to support a variety of networking protocols. Now it only does netsync. This is because the older networking protocols were based on log replay, which inherently produced coupling between clients and servers. The netsync protocol always works out what to send and receive "on the fly". This is something which is not as easy to do -- especially not so efficiently -- over HTTP, NNTP and SMTP. + += What is the "server"? = +There is no separate server software. Each client can act as a server by running the `serve` command. When a client contacts a server, it can send and receive facts the server has not yet seen; these can be facts about the client, or facts about other peers. There is no coupling between each client or server, so if one server goes offline, any other client can take over the role of server for a group of users. + +This design follows the philosophy of "end-to-end" networking, putting the brains of the system in the clients, and relegating network communication to the role of exchanging "dumb" informative data packets. Each network exchange is stateless, and monotone does not rely on the identity, location or availability of a particular networking host between exchanges. + +Netsync exchanges can also be tunneled through SSH, so running a dedicated `mtn serve` process is not required. + += Why an embedded SQL database, instead of Berkeley DB? = + * There is a nice little command-line tool to manipulate databases by hand. You should never have to use it, but it is good to know it is there in emergencies. + * Sqlite is actually smaller and simpler than Berkeley DB, as it has far fewer adjustable knobs and modes of operation. + * SQL has a much richer data vocabulary built-in (tuples, uniqueness constraints, joins, indices, sorts, globs, unions, intersections, etc.) + * Sqlite keeps to a single file, rather than a directory of files. + * The SQL command stream is ascii; we can (and do) log all database activity to the internal diagnostic buffer, which makes debugging very easy. + * The state of the database is one big SQL statement, which you can dump out and edit in vi. + * It leaves the door open to retargeting monotone to a larger RDBMS without much effort, if it's attractive to do so someday in the future. (Though, it has become clear that SQLite performs excellently, and it isn't clear why this would be attractive; see below.) + += What about "real" SQL databases? Can I use monotone with PostgreSQL/MySQL/Oracle/...? = +Like many things, if you wrote code for this, it could be made to happen. However, it probably won't accomplish what you want. + + * Some people want this so they can let multiple people access the same repository at once. However, this will not work; monotone prohibits concurrent access to a single repo for reasons of simplicity, robustness, and confidence in correctness. We agree that it is occasionally annoying that access to the database is serialized (though less annoying than many people expect), so we would be very interested in a plan for how to permit it in a way that is both safe, and obviously safe. + * Some people want this so they can use their standard database backup tools. Monotone already provides a much better solution for backups: the basic communications operation in monotone (netsync) is exactly an efficient, online backup mechanism. Every developer working against your repository has a complete local backup of whatever project(s) they are working on; in addition, it is easy to set up as many other backup database as you like, synchronized as often as you like. Furthermore, these backup databases are actually hot spares; if something should happen to the usual server, developers can simply point their clients at one of them and keep working as usual. They can also be used for load-balancing, by simply letting developers use whichever one they like normally, and having their changes propagated around to the other servers by the normal backup pulse. + * Some people want this because they think it will make monotone faster. This is probably incorrect; SQLite is already generally faster than other databases, because being entirely in-process gives it much lower overhead. Furthermore, monotone is very chatty with the database, often issuing hundreds of SQL commands at a time, which works fine when the "database" is just an in-process library, but would be quite slow when each command has to go out of process and come back again. + * Some people want this because they think it will make monotone scale better to large histories. This is possible; while SQLite 3 can in theory handle multi-terabyte databases, and we've seen it handle multi-gigabyte databases, no-one will know for sure how well it performs until someone actually tries. (Probably monotone itself will have more problems scaling to terabyte-sized histories than SQLite, though.) "Fixing" this now, though would probably be premature optimization. (Also, do you really expect to get a multi-terabyte history? GCC's 70,000 commits over more than a decade only come to a gigabyte or two.) + +So, overall, there are no technical advantages to using a traditional RDBMS, and some compelling disadvantages -- and this is not even including the relative administrative costs of "a file" versus "a daemon, with its own access controls, administration, users, ...". + += Can monotone store binary files? = +Yes. Monotone's internal delta storage format is byte-oriented: it is an implementation of Josh Mac''''''Donald's xdelta system. + += Can I convert CVS archives? = +Yes. Monotone can parse RCS `,v` files directly, synthesize the logical change history across a CVS repository, and import the results into a monotone database. No extra software is required. The conversion also converts branches, but does not connect them. This is being worked on. + += Why not use GNU diff format diffs with GPG signatures? = + * Classical diffs don't do binary very well. + * GPG as a subprocess is slow, tricky and fragile; using the botan crypto library in-process is fast, simple and reliable. + * Classical diffs may be whitespace-mangled, which invalidates signatures, so you need to ascii-armor it anyways. + * OpenPGP packet format is quite baroque, we need much ''less'' than it can do. + * The web of trust is useful for verifying that the name on a key matches the name on a passport. It isn't very useful for verifying that the holder of a key should have commit access to your project. We like to trust keys based on the quality of the code they sign, not based on the name attached to them. (In fact, every VCS we know of that does use OpenPGP keys doesn't leverage the web of trust at all, but rather requires you to explicitly upload each key you want to trust.) + * In the rare case where you do know that the person whose passport says "Jane Doe" is a hotshot coder who should definitely have commit access, you can always ask her to just PGP-sign her email saying "my monotone key's fingerprint is 70a0f283898a18815a83df37c902e5f1492e9aa2". + * You likely don't want to use your real PGP key for developing software in any case; most PGP keys should not, for instance, be put on a laptop that might be stolen. Yet many people would like to develop software while using their laptops. + += Why don't you assign "version numbers" to files / trees, like "2.7"? = +We thought to do this at first. But after discussion it seemed that to assign such numbers uniquely, you are faced with needing either a common authority to appeal to, or a really large number-space in which you will likely not collide. Then we thought, well, in the case of the latter, why ''not'' just use a content hash? Then it became apparent that lots of nice things happen for free when you make that choice. So we stuck with it. + +People still ask for version numbers, but we don't know of any way to assign them that gives unique, sensible identifiers to all revisions (remember that there's much more branching and merging in monotone than in, say, CVS), and that keeps these identifiers stable in a distributed environment (i.e., existing revisions don't get new numbers when you commit or sync), and that assigns numbers consistently (so I can use a version number when talking to you, and trust that it will mean the same thing to you that it does to me). + += Isn't there a paper that proves that SHA1 codes are no good for version identifiers? = +You probably mean [http://www.nmt.edu/~val/review/hash/index.html this paper]. + +We think that paper is wrong. We have written a more [http://www.venge.net/monotone/docs/Hash-Integrity.html detailed response] in the manual, if you would like to examine it for yourself. + += How do I work in "lock step" with other users? = +You don't. Like CVS, monotone acknowledges that users work in parallel, and that the task of a version control system is to help ''manage'' the divergence caused by parallelism, not eliminate it. Unlike CVS, there is no such thing as a "central" monotone server, which tracks the unique head state of a branch. Each branch can have multiple "parallel" heads. + += If I make a change in parallel with a colleague, what happens? = +You produce divergence. When you and your colleague exchange packets, you will find that the branch now has two heads, not one. One or other (or both) of you can then ''reduce'' the divergence by performing a merge. + += If we both merge, doesn't that recreate divergence? = +Maybe, but probably not. If you both do an automatic merge using the same algorithm (built into monotone) and arrive at the same merged tree state (identified by SHA1 -- a content hash), then there is no divergence anymore. + +If one of you has to manually intervene in the merge, you will produce two new heads, but unless your intervention involved the ''entire'' merge, your two new heads will be ''closer together'' than the two heads you had going into the merge. You can try again on the next exchange. Nothing breaks when there are multiple heads. + += Isn't multiple heads on a branch dangerous or crazy? = +Not at all. CVS implicitly lets your entire team maintain multiple heads (in their working copies) all the time. Monotone just records the fact in the database, so it doesn't get "lost" in a clobbered or unavailable working copy. + +Here is an example: have you ever had a CVS working copy with an interesting change on your desktop, and wanted to move it to your laptop, or take it home for the evening to tinker with? Using CVS, the divergence is "hidden" from the CVS server until you commit, by which time it must be "resolved". Using monotone, you can commit whenever you like; you will just make a new head. You can check out that new head and continue to work on it (at home, on a laptop, wherever) until you're satisfied that it's OK, then merge with your colleagues. + +Monotone takes the approach that divergence is a fundamental part of being a VCS. Divergence always happens. The proper role of a VCS, then, is not to try to prevent or hide divergence, but instead to make it ''visible'' and provide ''tools to manage it''. + += How is that different from "lightweight branches"? = +Not very different at all. Every time you commit, you may be making a fork in the storage system. In monotone's view, a branch is just a set of instructions about which forks you want to merge and which ones you want to remain not-merged. If you want your fork to remain not-merged with your colleagues, you put it on a different branch. That's all. + += Can you "cherry-pick" changes from one branch/version to another? = +''Update:''' Yes. Visit CherryPicking for information on the new '''pluck''' command. ============================================================ --- wiki/FeatureAccessControl.moin 8f7c9fe5d34752bad05c8c3007c49f0a8fc20fda +++ wiki/FeatureAccessControl.moin 8f7c9fe5d34752bad05c8c3007c49f0a8fc20fda @@ -0,0 +1,29 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Provide Access Control features to provide limits over the actions developers can take + += Supported = + +Monotone has extensive and extremely powerful features for deciding which developer actions should be accepted. However, they're quite unusual and quite different from what other systems offer. So much so that people coming from existing VCS tools (especially centralised ones) might not even ''recognise'' them as Access Control features at first. + +In monotone, it is far more important what comes out of the db than what goes in. These features concentrate much less on restricting what a developer can do or say or publish into the repository, and much more on giving the end user the power to be selective about how and when they use that information later. Network exchange is a simple communication of facts (file contents and revisions) and assertions about their value (in certs) - but those assertions may not necessarily be believed. The TrustFoundations page describes how these concepts work in more detail. There are simple netsync permission hooks that mediate basic access control to servers, but everything else is better done via trust evaluations at the time of usage. + +In part this is a recognition of the unavoidable consequences of the offline, distributed nature of the system - any programmatic attempt to restrict software behaviour is subject to tampering by someone in full control of their own system and database contents. But it turns out to be a far better way to deal with a number of other requirements as well. + +Access controls are applied by users over what revisions and developers' code can come ''out'' of the database and have access to their workspace. Users can have different workspaces, for different purposes, with different trust settings appropriate to each purpose - taking revisions and information from the same database. New assertions can be made about old revisions at any time, and these may change how and where those revisions are considered trusted. + +For example, a common use for these kinds of features in other VCS tools is to restrict commits in specialised branches to a limited number of approved committers. In a centralised system, these controls would be enforced by a MasterRepository. Release Branches are a common example, where a release engineering team must review and approve all changes. In monotone, the revision can be committed first, published, then reviewed, and finally `approve`d onto the release branch by someone developers trust to make statements about code quality for that branch. This is just one example, and the capabilities are very powerful indeed. + +However, the flip-side of this unusual approach is that few projects are accustomed to working this way, and many users don't want to have to configure these kinds of rules for themselves. Monotone allows a very distributed and loosely structured development community to share information much more readily than they might with other tools, but many projects are more structured and generally involve certain authority figures who most users are happy to delegate these trust decisions to. The next major feature development effort in monotone, now that the core VCS functionality is robust and stable and mostly complete, is a set of VersionedPolicy mechanisms. This will allow users to delegate the configuration of these trust decisions to a suitable project authority or authorities for the sake of simplicity and convenience. + += Further Reference = + +Manual and Tutorial Sections: + * TrustFoundations and UsingCerts + * [http://venge.net/monotone/monotone.html#Hooks Trust Evaluation Hooks] + * [http://venge.net/monotone/monotone.html#Hooks Netsync Permission Hooks] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureACL VCSFeatureACL] ============================================================ --- wiki/FeatureAtomicCommit.moin 469132dcb1d0fb699a76631859bc0ea9e6ceb6ae +++ wiki/FeatureAtomicCommit.moin 469132dcb1d0fb699a76631859bc0ea9e6ceb6ae @@ -0,0 +1,28 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Commits to multiple files and directories happen all at once, as a single cohesive change set in isolation from other changes. + += Supported = + +Monotone commits are atomic and each produces a discrete revision. + +In addition, you can `commit` at any time to record the current state of your workspace safely. Monotone supports (and encourages) multiple ''heads''. You don't have to worry about whether your workspace or repository are up to date with respect to other developers' changes, and you don't have to be interrupted by a need to merge your work with other changes before you can commit. Merging happens as a separate step, when you are ready, and you can always go back to the starting point you just committed if the merge turns out to be difficult. + +Commits are atomic both in the VCS sense of a single revision across the entire file tree, as above, and also in the database sense: see FeatureRobustRepository. + += Example Usage = + +{{{ + $ mtn commit +}}} + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Dealing-with-a-Fork Dealing with a Fork] + * CommitEarlyCommitOften + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureAtomicCommit VCSFeatureAtomicCommit] ============================================================ --- wiki/FeatureBuildIntegration.moin 2dd9641c27e5a6c155f65eb2a07df3fda444f892 +++ wiki/FeatureBuildIntegration.moin 2dd9641c27e5a6c155f65eb2a07df3fda444f892 @@ -0,0 +1,20 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +It should be possible to trigger build and test systems to react to commits. + += Supported = + +Monotone has extensive hook and trigger facilities using lua. Monotone uses BuildBot for its own build-testing infrastructure, integration of other systems like Tinderbox should be quite simple. Contributions of script snippets and configuration documents are welcome! + +Monotone is designed from the start to be integrated with other tools, to support distributed workflow and project development processes. UsingCerts, in particular `testresult` certs, such QA tools can publish their results for each revision back to the distributed development community, who can then depend on these results when choosing suitable code to work with. + + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Quality-Assurance Quality Assurance] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureTinderbox VCSFeatureTinderbox] ============================================================ --- wiki/FeatureCVSExport.moin ef43adf7b60c45efe9bebafd0fd9cc69f4d58841 +++ wiki/FeatureCVSExport.moin ef43adf7b60c45efe9bebafd0fd9cc69f4d58841 @@ -0,0 +1,18 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Put revisions committed to monotone back into a CVS repository, to allow gradual migration or support interaction between projects using different tools. + += Not (yet) Supported = + +This is not yet supported in mainline monotone, but there is experimental code on a branch which does this (see BranchStatuses). + +Allowing developers to use ["MonotoneAndCVS"] together in several different ways is an explicit goal of this effort, but it is complicated by the well-known limitations of CVS. In particular, accurately representing the DAG-structure of monotone commits in a linear CVS history presents special challenges. + +It is an explicit goal of this development effort to eventually support replication of this kind with multiple different repositories, whether CVS or other VCS tools, including relaying changes between them via monotone. That ambitious goal is still some way off, however. + += Further Reference = + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureCVSExport VCSFeatureCVSExport] ============================================================ --- wiki/FeatureCVSImport.moin cab653a8e28ccc3be9552b893ead580eeb91a68b +++ wiki/FeatureCVSImport.moin cab653a8e28ccc3be9552b893ead580eeb91a68b @@ -0,0 +1,28 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The ability to import past project history from CVS and make it available to future development (so that diff, log, and other operations work as expected. + += Partially Supported = + +monotone can import cvs history, including collecting together changes in multiple files into synthesised change sets. The `cvs_import` command provides this feature; this is just one of several ways of working with ["MonotoneAndCVS"]. + +The primary limitation is that CVS branches are presently not attached to the revisions they branched off from: each is an independent linear history. Work is underway to resolve this limitation. + += Example Usage = + +To import a full CVS history, you need a copy of the cvsroot `,v` files: +{{{ + $ mtn -d /some/path/project.mtn cvs_import -b org.project $CVSROOT/dir +}}} + +This will create a branch called `org.project` with contents and history that you would get from `cvs co dir`. Any CVS branches in that history will be created with names like `org.project.cvs-branch-name`. + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Importing-from-CVS Importing from CVS] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureCVSImport VCSFeatureCVSImport] ============================================================ --- wiki/FeatureCommitMail.moin fb5b17ceb5b3bf9a695dda9d061588219009da12 +++ wiki/FeatureCommitMail.moin fb5b17ceb5b3bf9a695dda9d061588219009da12 @@ -0,0 +1,19 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Commits should trigger email notifications with the commit log message and details of the changes + += Supported = + +Monotone supports this and many similar kinds of actions and triggers via hooks. + +There is a hook that can be invoked on commit, but this will run on the individual developer's machine where the commit is done offline. It would be more usual to generate these messages instead when the committed revisions arrive via netsync at a convenient public server (see MasterRepository) with the appropriate email infrastructure. Monotone also includes a hook implementation for emitting events to [http://cia.navi.cx/stats/project/monotone CIA], from where the notifications can also be sent to IRC channels and RSS feeds. + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Hooks Event Notification Hooks] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureCommitMail VCSFeatureCommitMail] ============================================================ --- wiki/FeatureCompactRepository.moin a7eb23003f1e60e43667394887705a52fb89bc18 +++ wiki/FeatureCompactRepository.moin a7eb23003f1e60e43667394887705a52fb89bc18 @@ -0,0 +1,39 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The repository storage format should be compact and efficient, so that it is convenient for developers to keep replicated copies. + += Supported = + +Monotone compresses file and delta storage with gzip before writing to the database. For typical source file content and large projects with long histories, the resulting database file is usually similar or smaller than the corresponding CVS `,v` files. Storage size has not been a particularly strong development focus, and some information is stored uncompressed for fast indexing and searching. Further efforts at more compact storage forms could be made, but are not considered particularly important for size results alone at this stage given the already good results - such changes may happen in the course of making performance or other improvements as well. + +Monotone's storage format is also very convenient: it is a single [http://www.sqlite.org SQLite] database file (by convention with a `.mtn` extension). There are no trees of history files consuming inodes in hidden/dot directories scattered throughout the workspace. One database can be shared between many workspaces on the same machine, so there is no need to duplicate the history storage when working on several independent changes or along several different branches, each in their own workspace. Each workspace has a single `_MTN` metadata directory at the root, with a handful of small files, one of which includes a reference to the database to use for operations within the workspace. + +A number of useful and important operations can be performed on the database file without ''any'' workspace, so long as arguments normally inherited from the workspace are provided explicitly: network `sync` operations, branching and merging, diffs between revisions, log review, and others. + +The database format is machine- and endian-independant, and so databases can be quickly copied between machines where necessary or useful, including as a potential communication channel. History can be transferred or recovered from a copy of a db file on a CD or DVD, as one example. + +See also: FeatureRobustRepository + +## = Example Usage = +## +## come up with a better example +## +## To check out multiple workspaces +## +## {{{ +## $ mtn -d monotone.mtn db init +## $ mtn -d monotone.mtn pull venge.net '*' +## $ mtn -d monotone.mtn co -b net.venge.monotone +## $ mtn -d monotone.mtn co -b net.venge.monotone.experiment.foo +## }}} + += Further Reference = + + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Database Database Commands] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureGoodRepositoryFormat VCSFeatureGoodRepositoryFormat] ============================================================ --- wiki/FeatureEmbeddedIDs.moin 5e31f7b8fe2e8e5981fd37021776c4f3f7ce6589 +++ wiki/FeatureEmbeddedIDs.moin 5e31f7b8fe2e8e5981fd37021776c4f3f7ce6589 @@ -0,0 +1,18 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The ability to embed in file content the revision ID of the revision it came from. This is useful for identifying the source when the file becomes detached from the workspace and from monotone, such as when it is used to generate a derivative form (like an executable or html-rendered web page), or if the file has been imported into another project's VCS. + += Partially Supported = + +Monotone does not directly support automatic expansion of version strings or other keywords inside file content. Because the SHA-1 hashes of file content are crucial, and because these kinds of flags have proved difficult and confusing in some other systems, implementation of this feature has been avoided up to now -- mostly for lack of a compelling use case. It is certainly possible to add. + +Some of the cases where this kind of feature is used in other systems are better addressed by other mechanisms in monotone; in particular it is considered better practice to use the overall revision of the tree rather than a per-file identifier. Monotone uses this for its own embedded version in the executable, accessed via ``mtn --full-version``. Because monotone supports distributed, offline operation, there is also less need for embedded identifiers to determine a file's revision status. Finally, a file's SHA-1 hash '''is''' its identifier, so unchanged files can be identified in this manner. + +It is possible to approximate this feature, if needed, using hooks. A custom attr could be attached to files that need such expansion, and an attr-hook defined in lua to perform the substitution. Another possibility may be an implementation similar to that used to handle platform-specific newline formats, generalising that to other kinds of filters. In any such implementation, it would be vital to ensure that the content of the file seen for commit has been sanitised to contain only the bare keyword in a 'canonical' form that is stable between revisions. + += Further Reference = + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureDollarFreeBSD VCSFeatureDollarFreeBSD] ============================================================ --- wiki/FeatureFast.moin f1f75891942a3cb75dce7f4e56d86e505bc5be52 +++ wiki/FeatureFast.moin f1f75891942a3cb75dce7f4e56d86e505bc5be52 @@ -0,0 +1,28 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The VCS should be fast, especially for common operations. + += Partially Supported = + +Monotone is fast for many operations, including most common ones in a workspace like `diff` and `status` and `commit`, but not universally so. Monotone's speed results are mixed, but improving rapidly. + +Monotone has been implemented for robustness and correctness first, and optimisation later. It includes extensive internal consistency checking and revalidation of information (see FeatureRobustRepository) and this comes at some cost in performance. The implementations of some key internal operations have been initially written for clarity and simplicity rather than efficiency, and some are known to be downright wasteful of CPU. These are being optimised or rewritten as benchmarking shows where the hotspots are; this can be done with confidence on the basis of the extensive test suite that ensures correct behaviour is retained with new implementations. + +Some operations are known to scale poorly on repositories with very deep histories, even though the problem may not be noticable on newer projects with shorter histories. The 0.30 release introduced major performance improvements as a result of applying this process to some key areas, and further work is ongoing to continue this process for more elements and internal operations. + +The user operations known to be slow include: + * initial `pull` of long histories into a fresh db (it is possible to work around this by copying the db file to get started instead) + * `cvs_import` of long CVS histories into a fresh db (essentially the same problem, but without the workaround) + * `mtn annotate` + +PerformanceWork is active and ongoing to address these issues. Even for deep histories, common developer operations within a workspace are quite fast: usually the limiting factor is disk seek speed reading workspace files to check for changes. + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Inodeprints Inodeprints] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureFast VCSFeatureFast] ============================================================ --- wiki/FeatureLightweightBranches.moin aad2b4d0e1090373a9a1ff2625a4ab051ca08f97 +++ wiki/FeatureLightweightBranches.moin aad2b4d0e1090373a9a1ff2625a4ab051ca08f97 @@ -0,0 +1,29 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Easy and cheap branching to allow parallel lines of development, and sophisticated history-aware merging for keeping branches in sync. + += Supported = + +Monotone's implementation of branches is ''extremely'' lightweight, and quite different to that in many other systems. + +Revisions can be in multiple branches (or none). Revisions can be added to branches long after they are first committed, perhaps after testing or code review to determine that they are suitable. Monotone separates completely the concept of a file's history (which is important for merging) from the concept of a branch (which is important for developers keeping track of the ''purpose'' of a particular development effort and view of the code). The BranchAnalogy describes the separation of these concepts. + +Monotone also has very robust and powerful merging capabilities (see FeatureMerging). + += Example Usage = + +To commit some changes in a workspace to a new branch: +{{{ + + $ mtn commit -b com.example.new-branch-name +}}} + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Branching-and-Merging Branching and Merging] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureBranch VCSFeatureBranch] ============================================================ --- wiki/FeatureLogReview.moin af13f2028f5066c6c465554cd4aca95cebdfc685 +++ wiki/FeatureLogReview.moin af13f2028f5066c6c465554cd4aca95cebdfc685 @@ -0,0 +1,23 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The ability to check and enforce style or other formatting guidelines on log messages + += Supported = + +Monotone supports the validate_commit_message hook, which is passed a user's intended commit message and details of the revision about to be committed. Hooks are implemented in lua, and can make arbitrary programmatic assessements of the log message to decide whether to accept or reject it. The default hook simply rejects empty messages. + +Note that these hooks are run on individual developer machines where the commits are done, offline. These developers could remove the hooks and commit noncompliant messages if they wanted (though of course those messages are signed so this misbehaviour is clearly their own responsibility). + += Example Usage = + +See also: UsingCerts + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Hooks ValidationHooks] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureLogReview VCSFeatureLogReview]. Note that the example given talks about "approved by: re" messages. While these might be appropriate in logs too, monotone has much more extensive and flexible mechanisms to handle approval of revisions for particular purposes and branches. See TrustFoundations and FeatureAccessControl. ============================================================ --- wiki/FeatureLogTemplates.moin 6b95d3adfff23d25a6dbae1febe95f054f80427b +++ wiki/FeatureLogTemplates.moin 6b95d3adfff23d25a6dbae1febe95f054f80427b @@ -0,0 +1,16 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Commit log messages should start from a predefined template that prompts the developer to fill in certain information or follow certain conventions. + += Not Supported = + +This is not presently supported, but would be simple to add - just nobody has gotten around to doing it yet. Like a number of other similar simple features and good ideas, this is one of the QuickieTasks that would be a great way for a new contributor to get used to the monotone code. + +It is possible to test the commit message for compliance to rules (see FeatureLogReview), and it would also be possible to implement this using hooks. One suggestion would be to use a hook on other commands (like update) to copy the template to `_MTN/log` if it is empty. + += Further Reference = + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureLogTemplates VCSFeatureLogTemplates] ============================================================ --- wiki/FeatureMIMEtypes.moin cbefa97b30b877d7567618f7f1bc4b81ac464dee +++ wiki/FeatureMIMEtypes.moin cbefa97b30b877d7567618f7f1bc4b81ac464dee @@ -0,0 +1,25 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Annotating binary files in the repository with MIME-type information indicating how it should be handled. + += Supported = + +There is no explicit support for MIME-type information specifically; monotone has no particular use for this information internally, and will simply store binary files like any other. However, this and any other similar information about files can be stored in a custom attr on the file, and any special file handling related to the mime type can be defined in an attr hook. + += Example Usage = + +{{{ + $ mtn attr set *.html MIMEType text/html + $ mtn commit +}}} + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#File-Attributes File Attributes] + * [http://venge.net/monotone/monotone.html#Hooks Hooks: Attribute Handling] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureMIMEType VCSFeatureMIMEType] ============================================================ --- wiki/FeatureMerging.moin 8c6ec6653a5f36e274b737147a00ee451e454c69 +++ wiki/FeatureMerging.moin 8c6ec6653a5f36e274b737147a00ee451e454c69 @@ -0,0 +1,38 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Automated and assisted merging of divergent revisions. + += Supported = + +Monotone has very robust and powerful merging capabilities, which work based on the DAG history structure, independent of branches. These capabilities work regardless of how developers choose to use branches. + +The merge, propagate and explicit_merge commands all access the same underlying merging capabilities, and differ only in how they select the revisions to be merged. merge picks multiple heads of the same branch, propagate merges the changes along one branch into another, and explicit_merge lets you pick whatever you like. + +The `update` command will use the same merge between a repository head and local changes in the workspace, but this is in general not recommended. Instead, recommended practice is to commit local changes first (multiple heads and explicit branches are cheap) and then merge with incoming revisions from other developers separately. + +Each of these commands will invoke external merge assistance tools (defined with merge hooks) to help developers choose changes and resolve conficts. + += Example Usage = + +A very common developer loop: +{{{ + + $ mtn commit + $ mtn pull + + $ mtn merge + $ mtn sync + + $ mtn update +}}} + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Branching-and-Merging Branching and Merging] + * DaggyFixes and ZipperMerge + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureMerging VCSFeatureMerging] ============================================================ --- wiki/FeatureMirroring.moin baf14ce474fc0b2a7e726b4a16b22c90836ec5fa +++ wiki/FeatureMirroring.moin baf14ce474fc0b2a7e726b4a16b22c90836ec5fa @@ -0,0 +1,33 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Support replication or mirroring of the repository to remote sites, for load distribution and/or backup purposes. + += Supported = + +This feature is fundamental to monotone, as a distributed VCS. There is essentially no other way of working, because every developer works with their own repository replica. + +Not all repositories are used for the same purpose, though. A project may choose to set up several servers, distributed geographically, to spread the load of software distribution and the risk of hardware or network failure. It is easy to set up automated replication between servers, or to rely on users to relay new revisions between servers. + + += Example Usage = + +If independent monotone servers are running at `server1` and `server2`, a developer with write privileges to both servers can replicate content between them simply by syncing with each server: +{{{ + $ mtn sync server1 + $ mtn sync server2 + $ mtn sync server1 +}}} + +If either of these servers had new revisions, those revisions will be transferred to the developer's database, and then to the other server if it was not yet aware of them. In order to make them identical mirrors, use the branch pattern `'*'` for all syncs, otherwise more selective patterns can be used for partial replicas. + +These servers are inherently peers, there is no particular need for any of them to be considered the MasterRepository. As discussed in that page, there is no particular need to back up either of these servers, their content can be restored from the other server, or from developer's databases - anything in a server database will also exist in one or more other databases where it was originally committed, at least. + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Network-Service-Revisited Network Service Revisited] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureMirroring VCSFeatureMirroring] ============================================================ --- wiki/FeatureNetworkSecurity.moin a6108cdc69b1566413971c22fefd6ad070b722ae +++ wiki/FeatureNetworkSecurity.moin a6108cdc69b1566413971c22fefd6ad070b722ae @@ -0,0 +1,25 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Network operations should be secure. + += Supported = + +Monotone's netsync protocol uses mutual authentication of client and server keys and has integrity protection, as do the signed revisions and file contents being transferred. It is recommended that servers use dedicated keys. + +It does '''not''' inherently include confidentiality protection via native encryption, but this can be added via port forwarding through SSH, IPSec, or other suitable means. Netsync also supports a direct ssh transport where a user has personal databases on two machines and ssh accounts and access between them; this is not scalable to many users as accessing a database via `ssh://` locks it, while the same database can be accessed by many netsync users concurrently. + +If you have confidentiality concerns about your revision contents (because you are working on a sensitive project), you will also need to protect the distributed database and workspace contents on disk as well as in transit across the network and in their use with other development tools. Several of these aspects are platform dependent and outside of monotone's direct control, so each project should select measures appropriate to their needs. + += Example Usage = + +''todo'' + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Basic-Network-Service Basic Network Service] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureNetworkSecure VCSFeatureNetworkSecure] ============================================================ --- wiki/FeatureObliterate.moin 07da7a6da68dddc91f5a1be4c91699dfbaeb00f4 +++ wiki/FeatureObliterate.moin 07da7a6da68dddc91f5a1be4c91699dfbaeb00f4 @@ -0,0 +1,37 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +To completely remove content and history of something committed inappropriately when necessary. + +Note that this is not the same as just backing out bad changes, which should be recorded as normal history. This is to remove content that must be purged, perhaps because it is legally encumbered or otherwise inappropriate. It's not something that will happen often, but can be very important when needed. + += Partially Supported = + +This is an especially challenging operation for monotone and any other distributed VCS, because of the replicated nature of the repository. It can be difficult to know where all the copies of the offending material may be, and even more difficult to exert control over all of those places. Ordinarily, this is a good thing: in monotone, it is and '''should''' be hard to remove history information by any kind of inadvertent command or accident or anything else other than a deliberate and organised effort. + +It is something that cannot be entirely addressed purely within software; consider the database on someone's backup CD or DVD as an example. This is therefore something that can only ''ever'' be partially supported by any distributed VCS application, and will require manual steps in accordance with the particular situation at hand. + +The problem arises if the offending revisions and content have been `sync`ed to other databases and spread from there. Even if all those copies can't also be destroyed, they need to be prevented from replicating back into the cleaned-up databases. The potential for a feature to filter and reject known-bad incoming revisions from netsync has been discussed but not yet implemented. This may be enough that a project can remove and prevent redistribution of the offending content from their own servers. Future work on policy and trust distribution mechanisms may offer further capabilities in this regard. + += Example Usage = + +Revisions can be removed from a local database, if they have no descendants: +{{{ + $ mtn -d database.mtn db kill_rev_locally +}}} + +If there are descendants, additional changes have been based on the bad revisions and they must also be removed. If they're unrelated and still wanted, they must be reapplied to an ancestor of the old revision (most likely using `pluck`). + +Removing the revisions does not remove the file content. This can be removed with a local sync to a new database, which won't transfer the now-unreferenced file content +{{{ + $ mtn -d new.mtn db init + $ mtn -d old.mtn sync file://new.mtn '*' +}}} + +These steps will need to be taken on all affected databases. If this number is known to be large, the branch epoch feature can be used to render clean and dirty databases incompatible and prevent accidental re-pollution. + += Further Reference = + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureObliterate VCSFeatureObliterate] ============================================================ --- wiki/FeatureOffline.moin e1fbc090b60dd2e43fc9871ef70d7c230662445c +++ wiki/FeatureOffline.moin e1fbc090b60dd2e43fc9871ef70d7c230662445c @@ -0,0 +1,33 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The ability for developers to work offline, without access to a network repository, and still perform most or all useful VCS operations. + += Supported = + +This is fundamental to monotone and fully supported. + +The ''only'' operations that use the network are those that transfer revisions: `sync` and its one-way cousins `pull` and `push`. ''All'' other operations, including `commit` and `merge`, are distributed and occur locally offline. Developers can continue to work offline, publishing their work and learning of the work done by others with a quick `sync` whenever network access is available. +Indeed, reasonable portions of monotone's own development has been done offline, such as while travelling, often because working on other projects would have been harder at the time. + +Even these operations do not necessarily need to use the network: revisions can be shared between developers by syncing with a database on a removable flash widget that moves between disconnected machines, as one example. + += Example Usage = + +All of the following (and many other things besides) work entirely offline: +{{{ + $ mtn log --last=3 file.c + + $ mtn diff file.c + $ mtn diff -r t:some-release-tag file.c + $ mtn commit +}}} + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Storage-and-workflow Storage and workflow] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureOffline VCSFeatureOffline] ============================================================ --- wiki/FeaturePortable.moin 58dc1094939cdd44ebb9fedc8c5d9fbb04458399 +++ wiki/FeaturePortable.moin 58dc1094939cdd44ebb9fedc8c5d9fbb04458399 @@ -0,0 +1,15 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The VCS tools should be portable to run on many kinds of development platform. + += Supported = + +Monotone is implemented in C++, and compiles and runs on all sorts of different kinds of Unix systems and Windows. It is packaged in a number of linux distribution and packaging systems, as well as NetBSD pkgsrc which itself supports a number of different systems: see BuildingViaPkgsrc. + += Further Reference = + + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeaturePortable VCSFeaturePortable] ============================================================ --- wiki/FeatureRename.moin 2c29e9571dc1e97d4794a9539a1d142ab33c0834 +++ wiki/FeatureRename.moin 2c29e9571dc1e97d4794a9539a1d142ab33c0834 @@ -0,0 +1,28 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Rename files and directories without losing history or breaking future merges. + += Supported = + +The `rename` command (also aliased as `mv`) will allow files and directories to be renamed without breaking forwards or backwards history. These changes can be committed along with content changes as a single revision. Commands that use the history, including `log` and `merge` and `annotate`, will follow files through arbitrary renames. Two revisions that rename the same original file to different names, or that rename two different files to the same new name, will (correctly) cause a conflict will need to be resolved before they can be merged. + += Example Usage = + +To rename a file: +{{{ + $ mtn rename -e foo.c bar.c + $ mtn commit + $ mtn log bar.c +}}} + +''(-e executes the change in the workspace filesystem as well as in monotone's history)'' + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#SectionName Manual Section Name] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureRename VCSFeatureRename] ============================================================ --- wiki/FeatureRobustRepository.moin a8f91a82b8581a5310e3e437d19a0b131afd9b36 +++ wiki/FeatureRobustRepository.moin a8f91a82b8581a5310e3e437d19a0b131afd9b36 @@ -0,0 +1,29 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +The repository storage format should be robust and resilient to problems caused by crashes, full filesystems, etc. + += Supported = + +Monotone's repository is stored in an ACID-compliant [http://www.sqlite.org SQLite] database file. All monotone operations that write to the database occur inside transactions, and so either happen completely or not at all. This includes not only normal VCS operations, but also administrative actions such as database schema upgrades that may occur from time to time as monotone develops. + +Monotone is almost fanatically pedantic and paranoid about internal consistency checking, and has a strict policy of failing early. If any problems are detected during an operation, monotone will abort rather than risking committing bad information to the database. This is a very particular kind of robustness that favours historical integrity over user perceptions where abrupt errors are triggered. These events are generally fairly rare, and always of interest to the developers, even if it means that a more user-friendly error message needs to be emitted. + +Monotone's extensive consistency checking has on several occasions revealed underlying hardware or other problems that have led to disk or memory corruption of data, either in the repository or in the workspace. Even under these or similar circumstances, if the worst should happen a corrupted repository can always be recreated as long as it has been replicated elsewhere. Revisions are revalidated on transmimssion over netsync, so we are very careful to ensure it should not be possible for any corruption to spread. + +Although the database storage layer is SQL, this is embedded within monotone; knowledge of SQL or the schema is invisible and irrelevant for all regular use. Even so, it is nice to know that SQL tools can be used when needed for extremely specialised operations. These circumstances usually amount to either debugging monotone, or specialised one-off administrative tasks that usually indicate the need for additional UI commands to be developed. The database storage layer and schema is also well isolated and abstracted within the monotone codebase: all the core algorithms and UI operations are entirely storage-agnostic, allowing other storage implementations or schema changes as needed. + +See also: FeatureCompactRepository + += Example Usage = + +Interrupt or kill monotone during any operation. + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Database Database Commands] + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureGoodRepositoryFormat VCSFeatureGoodRepositoryFormat] ============================================================ --- wiki/FeatureSignedRevisions.moin a4a5100a01dd26c8aa483a89a7fbfdb886eac4c3 +++ wiki/FeatureSignedRevisions.moin a4a5100a01dd26c8aa483a89a7fbfdb886eac4c3 @@ -0,0 +1,28 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Revisions and changes should be cryptographically signed to ensure historical integrity and detect accidental or malicious alteration. + += Supported = + +This is a primary and fundamental component of monotone. Revisions are identified by the SHA-1 hash of their ancestry+content, and additional metadata about these revisions is attached using signed certs. + += Example Usage = + +'''' + +{{{ + $ mtn ... + + $ mtn ... +}}} + += Further Reference = + +Manual and Tutorial Sections: + * [http://venge.net/monotone/monotone.html#Certificates Certificates] + * TrustFoundations and UsingCerts + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureSign VCSFeatureSign] ============================================================ --- wiki/FeatureSymlinks.moin 2a3964d71fbc071f92452d34365946fd56283c88 +++ wiki/FeatureSymlinks.moin 2a3964d71fbc071f92452d34365946fd56283c88 @@ -0,0 +1,18 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Store Unix Symbolic Links as versionable objects in the repository, and recreate them on checkout/update. + += Partially Supported = + +Monotone ignores symlinks by default, but extensions to store these can be implemented using attrs and hooks. These are under active development and in use at the moment and may be integrated into a future release. + += Example Usage = + +See UnixAttribsAndSymlinks + += Further Reference = + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureSymlinks VCSFeatureSymlinks] ============================================================ --- wiki/FeatureVendorBranches.moin f03506ca59fbef2f3df1f0fed561f86dd26fbe4a +++ wiki/FeatureVendorBranches.moin f03506ca59fbef2f3df1f0fed561f86dd26fbe4a @@ -0,0 +1,22 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +Import external sources from third-party vendors, and allow tracking and sensible merging of local changes with future vendor releases. + += Supported = + +Any branch can be used as a Vendor Branch. Unlike CVS, vendor branches are not treated specially in monotone. (This CVS feature with a single branch which behaves "magically" has now come to be seen fairly widely as a mistake.) + +There are two aspects to this requirement that are often used together: + * tracking "pristine" external sources in a separate branch + * using the sources in such a branch as part of a larger derivative project + += Example Usage = + +''under construction'' The VendorBranchPattern page (will) contain detailed recommendations for BestPractices in how this should be done. + += Further Reference = + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureVendorBranches VCSFeatureVendorBranches] ============================================================ --- wiki/FeatureWebInterface.moin 9157dd1e6ad73fddb4056fe1dc4e1af212c128fb +++ wiki/FeatureWebInterface.moin 9157dd1e6ad73fddb4056fe1dc4e1af212c128fb @@ -0,0 +1,22 @@ +This page is one of many describing EvaluationFeatures that may be useful when comparing monotone to other similar (and not-so-similar) VCS systems. + += Description = + +A web-based interface should allow for easy browsing of sources, history, logs, diffs, etc. + += Supported = + +There are a number of InterfacesFrontendsAndTools that work with monotone, including several web-based ones. Monotone's own sources can be browsed using [http://grahame.angrygoats.net/viewmtn.shtml ViewMTN], and there is also a [http://www.ipd.uni-karlsruhe.de/~moschny/TracMonotone/ Trac plugin] under development. + += Example Usage = + + * [http://viewmtn.angrygoats.net/branch.psp?branch=net.venge.monotone Recent monotone activity, via ViewMTN] + * [http://viewmtn.angrygoats.net/headofbranch.psp?branch=net.venge.monotone Current monotone HEAD revision] + * [http://trac.h975245.serverkompetenz.net/ Trac-monotone demonstration] + * [http://cia.navi.cx/stats/project/monotone Recent monotone activity, via CIA] + += Further Reference = + + +Features and Requirements in other evaluations: + * FreeBSD [http://wikitest.freebsd.org/VCSFeatureWebInterface VCSFeatureWebInterface] ============================================================ --- wiki/FileSystemIssues.moin 8d73f3572a576b94a792214523e2ae55fd329fa9 +++ wiki/FileSystemIssues.moin 8d73f3572a576b94a792214523e2ae55fd329fa9 @@ -0,0 +1,225 @@ += File System Issues in Monotone = + +About: Encoding, platform independency and case of filenames (codepages and unicode)[[BR]] +Related: CaseInsensitiveFilesystems + +Last updated with monotone version 0.32 + +I encountered some bugs and thought as it is my character: "I'm going to fix that quickly!". By now I know it better. This text consists of a few facts and a lot speculation. Formulations are often not precise due lack of knowledge, which this page should help to gain. I can tell you things are really hairy. There is a lot of misinformation, which I often copied to this text. There are exceptions of exceptions of rules. There are terms, which are used in wrong context. While writing this I tried to fix such errors, and every time I learned it better... so this text in its structure pretty much represents the chaos that is out there. + +directoryname and filename can be used synonymous. I hope I always used the word filename. + +== The facts == + + 1. Monotones copy libidn's stringprep does not work on mingw (win32). Calling "mtn löl" causes following output: [[BR]][[BR]] ?: error: failed to convert string from ASCII to UTF-8: 'l?l'[[BR]][[BR]] + a. There is a quick fix for that: call "chcp" get your current codepage and set it for example: "set CHARSET=CP850". + a. I traced down that stringprep_local_charset_slow in toutf8.c is disabled on mingw. + a. There is a new version of libidn which states to work on mingw (not tested). + 2. Recursively adding files ("mtn add -R") with umlauts will fail on systems that have other codepage than UTF-8 in their file systems. + a. file_io needs to be re-factored according to njs. + a. The directory walking code does not do any conversion at the moment. + 3. On Mac OSX you can add the same file (containing umlauts in its filename) twice: + a. You add the file using recursion, which will lead monotone to add a decomposed (NFD) UTF-8 filename. + a. You can add the file using the full path, which will lead monotone to add precomposed (NFC) UTF-8 filename. + a. To drop this file you need to drop it once using your keyboards umlauts (precomposed). (i.e löl) and once using bash's completion: lo-tab -> löl (decomposed). See "About UTF-8 normalization" below. + 4. Case insensitive file systems lead to the same problem as in 3 and sometimes to even more problems: CaseInsensitiveFilesystems + +Now for the speculation... + +== The speculations == + +This is a special problem, which probably only cross-platform SCM tools have. Even for tools like rsync this is not such a big problem, since the synced filename is possibly crap, but at least the contents are copied. And copying back will probably correct the filename again. But SCM Tools have to track these filenames on different platforms and file systems. Inconsistency will lead to errors in deltas, in merging... + +=== File systems === + +Most POSIX file sytems are transparent. They just accept the kind of encoding the user has set. + + * http://www.j3e.de/linux/convmv/ + +==== Linux (most POSIX) ==== + +Assuming I'm on linux: + +If I set the terminal to UTF-8 and call "touch löl" I create a file with UTF-8(NFC) encoded filename. When I call "ls" I will get the correct filename. If I set the terminal to ASCII and call "ls" I will get something like "löl". + +This means on most POSIX systems filenames with different encoding (ie. UTF-8 and LATIN-1) can coexist in the same directory. This is what is going to make it hard to find the correct solution for monotone to handle filenames. + +==== Mac OSX (darwin) ==== + +On OSX (UFS and HFS+) things are different. The VFS file system layer of OSX forces a filename always to be UTF-8 (NFD), which means you can create a file using UTF-8 (NFC) and read that filename (using readdir()) again and you'll get UTF-8 (NFD). You will also be able to open or find a file using UTF-8 (NFC), which explains why I was able to add the same file twice. You actually can open and find a file using NFC or NFD. Additionally HFS+ can be case insensitive. + +==== Windows win32 (NTFS / FAT) ==== + +NTFS enforces encoding to UTF-16 (or UCS2???), while FAT should not be used with UTF-8. It should not be possible to use FAT with UTF-8, since the file system layer of win32 will prevent that. There are linux implementations of FAT, which state that the file system is going to be case-sensitive when using UTF-8 with FAT. The file system layer of win32 will convert to current codepage when using ANSI versions of file system layer functions (at least my tests told me that). + +Microsoft recommends to use the wide version of all file system layer accessing function. + + The GetACP() Page states: The ANSI code pages can be different on different computers, or can be changed for a single computer, leading to data corruption. For the most consistent results, applications should use Unicode UTF-8 (code page 65001) or UTF-16 when possible. + +''But it does not state how you achieve that, since there is no SetACP(). So I think using the wide version of the functions should be save.'' + +'''Addition''': wilx found the setlocale() function, which will change the output of ANSI versions of function in the C Standard Library: [http://msdn2.microsoft.com/en-us/library/x99tb11d(VS.80).aspx] + + * http://msdn2.microsoft.com/en-us/library/ms776442.aspx + * http://en.wikipedia.org/wiki/UTF-16 + +So you probably can't use cygwin/mingw anymore: + + * http://www.cygwin.com/ml/cygwin/2006-11/msg00796.html + +-> Case insensitive, too! + +==== Some cases ==== + +Well, if you want to have different codepages going to at least sort of work, you probably have to guess what the best way is to solve some cases. Using the information: what platform are we on, which file system are we on. Some cases: + + 1. Two different files fall together on a case-insensitive file system, + 2. a file is written to the file system but can't be found again (the file system does some conversion), + 3. a file can't be written to the local file system because it won't accept the some character encoded in the file, + * as an example you have a chinese letter encoded in UTF-8 and the local locale is LATIN-1 -> iconv will give you an error. + * and different file systems have different reserved characters like /, + 4. we have double UTF-8 encoding, + 5. people change the locale while a workspace still exists, + 6. we convert from/to the wrong codepage to/from UTF-8 (can lead to wrong characters in filenames), + 7. filenames look ugly because the local locale can't represent characters in the name. + * This could happen if we decide to just make monotone 8-bit aware but not doing conversions at all. + 8. The NFC -> NFD problem. + +==== Solutions for single cases ==== + + 1. Internally enforce lower case, plus nice error messages on adding existing files. + 2. Find the file by content. Tell the user what happened and prompt if he likes to rename the file. + 3. Tell the user what happened and prompt if he likes to rename the file. + 4. Can we detect what encoding a filename is in? + 5. Save the current locale in the workspace. And reject commands on that workspace if the locale has changed. + 6. Can we detect what encoding a filename is in? + 7. Prompt the user to rename the file. + 8. Internally enforce NF? or respect "Canonical Equivalence" in string routines. (http://www.unicode.org/unicode/reports/tr15/) + +If monotone does care about conversion, the locales are set correctly and the file system or the user enforces that there are no filenames in other codepages than the locale defines (which should be common practice), case 2. / 4. / 6. / 7. can be avoided. The rest of the cases seems solvable, too. + +We can probably come up with a solution that could be called correct, except detecting misuse won't work in all cases, we have to trust in proper conditions. Some cases of misuse that work: + + * If conversion from UTF-8 fails: which is case 3. (actually not misuse, hmm) + * If conversion to UTF-8 fails: which probably is case 6. or 5.. We have wrong or mixed codepages in filenames. + * If the workspace locale does not match the local locale: case 5.. + +Not work will: + + * If conversion from the wrong locale leads to wrong but valid characters. + +==== The very restrictive solution ==== + +Let monotone only accept basic ASCII ([a-b], [A-B], [0-9], -, .) and always convert to lower case for comparing, store filename with case-information. Write nice error on non basic ASCII characters and if people try to add files which already exist, write a message that the problem might be that these only differ in case. + +This solution would even work if the file system converts characters to UPPER case, since we always convert them back on comparing. I have the feeling that this is the only solution, which possibly can reach a 100% correctness, also for futures changes and new platforms. + +==== The "we don't care" solution ==== + +Make monotone 8-bit aware. All strings are saved as 8-bit, but we don't do any conversion. It is the same as most POSIX file systems do. Possible cases: 1. / 2. / 3. / 7. / 8. + +==== The unicode solution ==== + +Only accept unicode UTF-8 on unix systems and UTF-16 (or using setlocale()) on windows. Always write filenames as UTF-8 on unix and UTF-16 on windows, regardless of the codepage / locale a user has set. Possible cases: 1. / 2. / 3. / 7. / 8. + +==== The solution that supports codepages and handles all cases ==== + +PLEASE INSERT HERE! + +Ok, I'll try to start listing what a sane solution should do (don't tell me I'm crazy :-)): + +Locale in this context means the codepage or encoding defined by the current locale. + +Read == A filename is read from local file system layer into monotone. (readdir())[[BR]] +Write == A filename is written to local file system layer from monotone. (open(), chmod(), chown(), stat(), mkdir()) + + 1. Do conversions on read (from locale to UTF-8) and write (from UTF-8 to locale) of filenames on POSIX, except Darwin. + 2. Do conversions on read (from UTF-8 (NFD) to UTF-8 (NFC)) and none on write of filenames on Darwin. + 3. One of the following solutions on windows: + 1. Do conversions on read (from locale to UTF-8) and write (from UTF-8 to locale) and use new libidn or GetACP() to find out what the local locale is. + 2. Use the wide versions of file system accessing functions on windows, which should return UTF-16. So you need to do conversions on read (from UTF-16 to UTF-8) and write (from UTF-8 to UTF-16). + 3. Use setlocale() to set UTF-8 and do no conversion. This differs from POSIX because win32's file system layer will do conversions. Tests on NTFS and FAT need to be done before using this solution. + 4. Convert all filenames to lower case for internal use, but save the filenames with case-information in the database, comparing should happen on uniform case. Write a nice error message on an add command, stating that the error could be caused by monotone not supporting case-sensitive filenames for the reason that there are case-insensitve file systems. Offer to rename that file. + 5. If there is a filename which has characters not supported by local locale (conversion from UTF-8 to locale fails). Write a nice error message explaining the situation. Offer to rename that file. + 6. If not the conversion, but the write (open() etc) fails, there should also be a sane message. This is probably because a filename violated reserved character restrictions of the local file system. Offer to rename that file. + 7. Save the current locale on a checkout in the workspace. Refuse futher commands if locale changes. Write a nice error message. Offer to update the locale in the workspace or recheckout the workspace. + 8. If conversion from locale to UTF-8 fails, write a nice error message that this might be caused by a filename, which isn't in the encoding defined by the current locale. Offer to rename that file. + 9. The local renaming of course has to happen without conversion, but the destination name must be convertable to UTF-8. If the file is added immediately after renaming, the destination name should be converted according to above rules. + 10. Good practice would be to check all possible conversion, read and write actions on a update, checkout and add command, write the corresponding error message and offer a way to fix the problem (mostly renaming the file). So the user will be informed about problems early. + 11. Writing unit-tests for 1-9. + 12. I added this "offer rename" statements because there are errors you can get on a checkout/update. So if you have no workspace (no update), you can't rename, if you can't rename you can get no workspace (no update). Therefore we need to offer some means of renaming while checking out or updating. + 13. There must be a migration function if we really are going to do 4., files which only differ in case must be listed and means of renaming them must be provided, when updating to the monotone version which implements 4.. + +Alternative solutions for case-insensitive FS are in CaseInsensitiveFilesystems, but I don't think they are conservative enough, on the other hand, if we really are going to only support the common subset, we need to implement "The very restrictive solution", which isn't nice, too. I'm glad I don't have to decide, but can just point out ideas. + +'''Important:''' This list is not thought as ALL OR NOTHING. Only the solutions that make sense for someone who knows the internals of monotone better than I do should be implemented. AND there are certainly variants of these solutions and some of them might make more sense. + + A variant to 12.: Checkout/update new filenames that can't be converted to local locale or can't be written with a automatically chosen filename. Write a message to the user with the orginal and the automatic filename and tell him he should use "mtn rename" to set useful name. So checkout/update will not fail. + +==== What did other people do? ==== + +There are several dozens of SCM systems which are cross-platform. How did they solve that problem? + + * Here is an rfc about ftp and unicode: http://tools.ietf.org/html/rfc2640 + * And the IETF policy on charsets: http://tools.ietf.org/html/rfc2277 + * The UTF8 rfc itself: http://tools.ietf.org/html/rfc3629 + + [[BR]]This is interesting (rfc2277): Negotiating a charset may be regarded as an interim mechanism that is to be supported until support for interchange of UTF-8 is prevalent; however, the timeframe of "interim" may be at least 50 years, so there is every reason to think of it as permanent in practice. + +==== And the angry comment ==== + +Boost should actually solve that, but it does not. I compared it with Qt and that doesn't do much more. + + encodeName(): By default, this function converts fileName to the local 8-bit encoding determined by the user's locale. This is sufficient for file names that the user chooses. File names hard-coded into the application should only use 7-bit ASCII filename characters. + +Wrong guess! + +* http://doc.trolltech.com/4.2/qfile.html#decodeName + + How should it fix something that seems not fixable. + +=== The terminal/console === + +Well, here most problems are solved by locales and the libidn. Except that it doesn't work on windows. Which can hopefully be solved by updating libidn or hacking the copy of libidn using GetACP(). + +http://msdn.microsoft.com/library/default.asp?url=/library/en-us/intl/nls_21bk.asp + +== About UTF-8 normalization == + +There are two commonly used normalizations of UTF-8: + + 1. NFC (mostly precomposed) used by the whole world. Except apple. + 2. NFD (decomposed) used by apple. [[BR]] +-> http://developer.apple.com/qa/qa2001/qa1235.html [[BR]] +-> http://developer.apple.com/qa/qa2001/qa1173.html + + Apple states: You can find a lot more information about Unicode on the Unicode consortium web site. Specifically of interest is the Unicode Standard Annex #15 Unicode Normalization Forms. As used in this Q&A, the terms decomposed and precomposed correspond to Unicode Normal Forms D (NFD) and C (NFC), respectively. + +Which is NOT totally true. There are characters that don't have a precomposed form, so these will exist in NFC as decomposed form. (http://www.unicode.org/unicode/reports/tr15/) + +=== Example === + + * precomposed is U+00[the latin-1 character] -> Á is U+00C1. + * decomposed is U+00[base ASCII char] U+[combining ACCENT char] -> Á is U+0041 U+0301. + +== What to do at the moment? == + +I use this script (http://fangorn.ch/n/blog/2007/01/20/isnotasciipl/) to check that all filenames are ASCII before I do a "mtn add -R". + +== Pages == + + * http://msdn.microsoft.com/library/default.asp?url=/library/en-us/intl/nls_21bk.asp + * http://msdn2.microsoft.com/en-us/library/ms776442.aspx + * http://support.microsoft.com/kb/147438/en + * http://developer.apple.com/qa/qa2001/qa1235.html + * http://developer.apple.com/qa/qa2001/qa1173.html + * http://en.wikipedia.org/wiki/UTF-16 + * http://www.j3e.de/linux/convmv/ + * http://tools.ietf.org/html/rfc2640 + * http://tools.ietf.org/html/rfc2277 + * http://tools.ietf.org/html/rfc3629 + * http://www.unicode.org/unicode/reports/tr15/ + * [http://msdn2.microsoft.com/en-us/library/x99tb11d(VS.80).aspx] + * http://fangorn.ch/n/blog/2007/01/20/isnotasciipl/ + +- Initial version by Ganwell ============================================================ --- wiki/ForSide.moin e919705b36da5a0e07b8879015d678ae520188f2 +++ wiki/ForSide.moin e919705b36da5a0e07b8879015d678ae520188f2 @@ -0,0 +1,28 @@ +## Please edit system and help pages ONLY in the moinmaster wiki! For more +## information, please see MoinMaster:MoinPagesEditorGroup. +##master-page:FrontPage +##master-date:2003-01-31 17:58:50 +#format wiki +#language da +#pragma section-numbers off + += MoinMoin Wiki = + +Et WikiWikiWeb er et kollaborativt hypertekst miljø, hvor styrken ligger i enkel adgang til og redigering af information. Denne wiki kan også linke til InterWiki rummet. + +MoinMoin er en Python Wiki:WikiClone, baseret på Wiki:PikiPiki. Navnet er et udbredt tysk slang-udtryk beskrevet på siden MoinMoin. Hvis du kører en Wiki vha. MoinMoin bedes du tilføje den +til siden MoinMoin:MoinMoinWikis. Der er bidrag af kode på siderne MoinMoin:MacroMarket, MoinMoin:ActionMarket og MoinMoin:ParserMarket. Flere detaljer og yderligere emner findes på MoinMoin-siden. + +---- +Du kan redigere enhver side ved at at klikke på linken i bunden af siden. Flere sammensatte ord med store begyndelsesbogstaver danner et WikiName, som er en hyperlink til en anden side. Klik på titlen for at få en oversigt over alle sider som refererer til denne side. Sider som endnu ikke er oprettet er markeret med et spørgsmålstegn: Klik blot på linken for at oprette siden. + +For en oversigt over dette site og hvad det indeholder, se siden SiteNavigering. + +Hvis du vil lære mere om hvad et WikiWikiWeb er, kan du læse MoinMoin:WhyWikiWorks og MoinMoin:WikiNature. Du kan desuden kigge i MoinMoin:WikiWikiWebFaq. + +---- +Interessante steder at begynde: + * SenesteRettelser: se hvad folk arbejder på for tiden + * HjælpForBegyndere: for at komme igang + * WikiSandKasse: du er velkommen til at ændre denne side og eksperimentere med redigering + * FindSide: Forskellige måder at søge og gennemse databasen ============================================================ --- wiki/FrontPage.moin b460fb25f23b4ad4515e8388f444438cb7e85f54 +++ wiki/FrontPage.moin b460fb25f23b4ad4515e8388f444438cb7e85f54 @@ -0,0 +1,127 @@ +## Please edit system and help pages ONLY in the moinmaster wiki! For more +## information, please see MoinMaster:MoinPagesEditorGroup. +##master-page:FrontPage +#format wiki +#language en +#pragma section-numbers off += monotone wiki = + +This is the wiki for the version control system [http://venge.net/monotone monotone]. + +monotone is a free distributed version control system. it provides a simple, single-file transactional version store, with fully disconnected operation and an efficient peer-to-peer synchronization protocol. it understands history-sensitive merging, lightweight branches, integrated code review and 3rd party testing. it uses cryptographic version naming and client-side RSA certificates. it has good internationalization support, few external dependencies, and runs on unix, OSX, windows, and is licensed under the GNU GPL. + +=== For Users === +==== About Monotone ==== + * ["Hosting"] + * ProjectsUsingMonotone + * EvaluationFeatures + * ["Testimonials"] + * ["Talks"] + * ["People"] + * MtnSummit2008 + +==== Getting Monotone ==== + * BuildingOnWindows and ["BuildingOnWindows/VisualC8"] + * BuildingOnMac + * BuildingOnSolaris + * BuildingViaPkgsrc on a wide variety of platforms + * MonotoneOnDebian + * SelfHostingInfo + +==== Using Monotone ==== + * InterfacesFrontendsAndTools -- other programs that work with monotone + * EssentialMonotone -- the minimal commands needed to get anything done + * AlternativeOverview -- a different order than the [http://venge.net/monotone/docs/Tutorial.html Tutorial] for introducing monotone capabilites + * BestPractices -- best practices for using monotone + * MasterRepository -- Master Repositories you might be used to with a centralised VCS, and why you don't need one with monotone. + * ["MonotoneAndCVS"] -- different ways of working with CVS and monotone. + * UsingCerts -- how certs work, and don't, in practice. + * TrustFoundations -- the basics of monotone's trust model, and how it works with certs + * BranchAnalogy -- understanding how monotone's branches work, and might be different to other tools. + * BranchNamingConventions and BranchRenaming -- discussions about how to name your branches and what to do when you change your mind. + * DaggyFixes -- handling bug fixes, backports, and cherry picking + * TipsTricksScripts -- useful snippets for getting more out of monotone + * TroubleShooting -- what to try when things aren't working + * RosterifyingPrivateBranches -- specific issues for those migrating private changes from monotone 0.25 and earlier to 0.26 and later. + * ReferenceCard - quick overview of monotone commands + * ["Glossary"] -- an explanation of some terms + * AutomateMagic -- some nifty things you can do with the automation interface + * WishList -- a list of features some people would like to have + +=== For Developers of Monotone === + * QuickieTasks -- This is a good starting point for new developers. + * NeedReview + * AutomateWishlist + * TrustDiscussion + * NetsyncTodo + * RostersTodo + * MagicSelectors + * BranchStatuses + * BugSquashingParty + * AttrUseCases + * HistoryBlueSky + * TestHarnessIssues + * TestIntro + * BuildBot + * MergeViaWorkingDir + * DatabaseLocking + * CaseInsensitiveFilesystems + * FileSystemIssues + * Win32DeviceFiles + * ["RevertUI"] + * SymLinks + * ["IPv6"] + * ["BranchUI"] + * SurveyQuestions + * RootDirRenaming + * I18nL10n + * PerformanceWork + * AutoInodeprints + * DeltaStorageStrategies + * LineEndingMunging + * NonMergeConflicts + * DocTodo + * CarrotAndStick + * CustomCerts + * TimeStamps + * VersionedPolicy + * ThingsStatusShouldShow + * CherryPicking + * PieceCache + * ["SpeedySpeedySHA1"] + * CertCleanup + * RevisionNumbering (Heights) + * NotesOnTestingChangesetify + * WorkspaceConflicts + * DatabaseCompaction + * ConflictFixupPolicy + * KeystoreFiles + * ["LogUI"] + * SimplerIgnoreMechanism + * RoadMap + * AutomateVersions + +==== Previous Activities ==== + * SummerOfCode2006 + * MtnSummit -- Mtn View 2007 + +Interesting starting points: + * RecentChanges: see where people are currently working + * WikiSandBox: feel free to change this page and experiment with editing + * FindPage: search or browse the database in various ways + * SyntaxReference: quick access to wiki syntax + * SiteNavigation: get an overview over this site and what it contains + + + +==== How to use this site ==== + +A Wiki is a collaborative site, anyone can contribute and share: + * Edit any page by pressing '''[[GetText(Edit)]]''' at the top or the bottom of the page + * Create a link to another page with joined capitalized words (like WikiSandBox) or with {{{["quoted words in brackets"]}}} + * Search for page titles or text within pages using the search box at the top of any page + * See HelpForBeginners to get you going, HelpContents for all help pages. + +To learn more about what a WikiWikiWeb is, read about MoinMoin:WhyWikiWorks and the MoinMoin:WikiNature. Also, consult the MoinMoin:WikiWikiWebFaq. + +This wiki is powered by MoinMoin. ============================================================ --- wiki/FutureCryptography.moin c98562ff69dfb2f85d5f1bce968b570253e1262e +++ wiki/FutureCryptography.moin c98562ff69dfb2f85d5f1bce968b570253e1262e @@ -0,0 +1,51 @@ +Because of our use of SHA-1, we must make backwards-incompatible changes to our use of cryptography. Since we will be paying the cost of a "flag day", we should consider how to get the most benefit from that cost. + += Cryptographic hash function = + +We must migrate to a new hash algorithm. + +SHA-1, the hash function on which everything in Monotone depends, has been broken. Eighteen months ago, Jon Callas of PGP described the state of SHA-1 thus: "It's time to walk, but not run, to the fire exits. You don't see smoke, but the fire alarms have gone off." It's time we picked up the pace of our move towards the exits. Bruce Schneier is predicting [http://www.schneier.com/blog/archives/2007/02/a_new_secure_ha.html] that there will be a live collision by the end of 2007. This will immediately mean that it's possible for someone to arrange for two different revisions to have the same hash, with consequences I haven't analyzed; more generally, it will put a cloud over the perception of Monotone's security, even though in practice a collision is considerably less damaging than a second preimage attack. + +NIST have started the process of agreeing a new hash standard in an AES-like process. This standard will be the AES-like gold standard of hash algorithms; I suspect it will also be considerably faster than existing hash functions, closer to PANAMA-like speeds than SHA-1 speeds [http://www.cryptopp.com/benchmarks.html]. Unfortunately it will not be agreed until 2012 [http://csrc.nist.gov/pki/HashWorkshop/timeline.html] and we can't wait that long. The obvious interim standard is SHA-256, which seems to have as much confidence as any hash function at the moment, and which is only a little slower than SHA-1. + +Should Monotone migrate to supporting more than one hash function? + + * Such support would make migrations much easier in future, and we'd very much like to migrate again at least once, in 2012. + * But a lot about Monotone works because there's a single hash function. I'd like to hear from those who know on what issues might be raised if a history uses more than one hash function. + * We have to consider carefully the security implications of supporting more than one - can an attacker just use the least secure one? + +There are some interactions with VersionedPolicy here. Perhaps hash functions would need to be mandated by policy. + +If we assume that "second preimage" attacks are infeasable but that collision generation might become feasable, things get interesting - attackers can't make new messages which match existing signatures, but they can probably cause ambiguous things to be signed. If you assume your attackers are not ahead of the curve on cryptanalysis, you could argue that signatures made before the attack are still valid, but those made after can't be trusted. Policy could explicitly bless all the pre-attack signatures but rule out future use of that hash function. + += Public-key signatures = + +As well as the hash function change, two other changes will impact on public key signatures: + + * Graydon proposes to change the Monotone cert format to make a single cert do the work of several, which makes sense. + * VersionedPolicy + +We should of course try to bring in all of these changes (and any resulting from the discussion below) at the same time to bring us down to one Flag Day. VersionedPolicy may also play a role in making some of this more straightforward. + +We should use "principals" - ie key fingerprints - everywhere we use keys. For that matter we should use them where we use email addresses too for the most part, though some of that comes under the heading of VersionedPolicy. + +We can reduce the computational burden of signature checking down to practically nothing with a couple of simple tricks: + + * A "math cache" in the database which records simply "this hash has been signed by this principal" so we don't have to do PK verification more than once per cert. + * Cert chaining - each cert should have a field to name a hash of another cert as valid. Contributors would thus chain together all the certs they sign in each branch. Though each cert should be separately signed, you could verify all of a key's certs in a branch with a single PK operation. Thus you'd end up doing one PK operation per netsync per branch - very fast. We shouldn't use this chaining for any purpose besides the optimization described here. + +== Signature standards == + +Monotone currently supports only one kind of signature: RSA-SHA1-EMSA3. This doesn't have a lot to recommend it in and of itself. It's an old standard that doesn't have a security reduction from the RSA problem, so it might be broken even if RSA itself is secure. And RSA doesn't have anything inherent to recommend it over Rabin-Williams, which is faster and has a reduction from factoring. + +One wrinkle is that a very recent branch of Monotone supports deferring signing operations to ssh-agent. This is fantastically convenient - ssh-agent securely stores your private key and you only have to tell it your passphrase once. It also means Monotone doesn't have to do the tricky job of keeping the private key private, even during signing operations. Unfortunately ssh-agent appears to support only two public-key operations, and there are problems with choosing either. + +Apart from that, we don't currently interoperate with anything. What should we be interoperating with? RSA-SHA1-EMSA3 is compatible with X.509 and thus SSL, but if we were to use the same key to sign X.509 certs and Monotone certs we would want to be very sure that one couldn't be presented as the other; it would almost certainly be better to have separate keys for the X.509 world and the Monotone world. These should not be RSA-SHA1-EMEA3 keys - we should use either EMSA-PSS or DSS. + +If we don't have any strong interoperability constraints, then we should seriously consider using elliptic curve cryptography, which gives us small signatures with fast verification. Note that with the tricks above the verification burden is hugely reduced, so we should be most pushed about signature size. + +Obviously we'd like to use something standard, but the world of standards is AFAICT in a difficult state at the moment - many of the standards we'd like to use have not caught up with SHA-256. In particular DSA and ECDSA are still bound to SHA-1. + += Netsync = + +Netsync's cryptography has both security and performance problems. Netsync is also quite unlike our use of cryptography elsewhere in Monotone. We should just bite the bullet and switch to SSL, while swallowing as little of X.509 as we can manage. ============================================================ --- wiki/Glossary.moin 2a6b1a782845668a8250f7d73e7871544d1b7fba +++ wiki/Glossary.moin 2a6b1a782845668a8250f7d73e7871544d1b7fba @@ -0,0 +1,44 @@ +''This page gives definitions for some of the technical terms and phrases you might come across in the advanced sections of the [http://www.venge.net/monotone/monotone.html manual], on the [http://lists.nongnu.org/mailman/listinfo/monotone-devel monotone list], or in this Wiki.'' + +[[Anchor(Cert)]] + Certificate:: (Normally: "Cert".) A note made against a revision. Certificates are used internally by Monotone - for example, to represent branches and to store the ID of the person committing a change - but can also be added manually by users. + +[[Anchor(Delta)]] + Delta:: The difference between two files, directories, etc.. The delta of two [#Manifest Manifests] is called a [#Revision Revision]. + +[[Anchor(Domain)]] + Domain:: Monotone uses this term to describe a group of variables held on a database. + +[[Anchor(Edge)]] + Edge:: The changes that come from one [#Revision revision] to a descendant. A merge would have more than one edge. In a [#DirectedAcyclicGraph Directed Acyclic Graph], one of the arrows, as opposed to one of the points. + +[[Anchor(Endpoints)]] + Endpoints:: `Need a definition here` "By restricting the set of trusted testresult certificates, you can require that the endpoints of an update operation have a certificate asserting that the revision in question passed a certain test, or testsuite." + +[[Anchor(DirectedGraph)]] + Directed Graph:: A diagram made up of points connected by arrows. In discussions about Monotone, this is normally just a shorter way of saying [#DirectedAcyclicGraph Directed Acyclic Graph]. + +[[Anchor(DirectedAcyclicGraph)]] + Directed Acyclic Graph (D.A.G.):: A diagram made up of points connected by arrows, where no arrow can lead back to an earlier point; in other words, the arrows cannot form a loop. If you drew a map of Monotone revisions, connecting each revision to each of its children by an arrow, this is the sort of graph you would be drawing. This is sometimes called the ''Revision Graph''. + +[[Anchor(Manifest)]] + Manifest:: Monotone's term for a snapshot of all the files in a working copy. + +[[Anchor(ManInTheMiddle)]] + Man In The Middle Attack:: A way of intercepting key-encrypted information sent between two parties (Alice and Bob) without either of them knowing. The third party pretends to Alice that they are Bob, and to Bob that they are Alice. This attack only works if Alice and Bob cannot authenticate each other's signatures by a second means, say, by reading each others' key hashes out over the 'phone. Monotone uses keys to prove the identity of the person signing a cert. + +[[Anchor(Packets)]] + Packets:: Monotone can be made to produce a text file containing a single revision. This text file is called a Packet. See also [#PacketStream Packet Stream]. + +[[Anchor(PacketStream)]] + Packet Stream:: Monotone writes data to disk in a Stream, in other words, at the time it changes. For efficiency the changes are `(presumably - help, anyone?)` sent to the database in Packets, in other words, grouped together. + +[[Anchor(Revision)]] + Revision:: Monotone's term for a record of the changes made to a [#Manifest Manifest] + +[[Anchor(Roster)]] + Roster:: It's like a manifest, except it also has various pieces of internal metadata used to make merging faster. In our data structures, this is split into roster_t, which maps nodes (files or dirs)to an id and holds the attributes (content hash (for files), attrs, (parent id, name)pair) for the nodes, and a marking_map which holds multi-*-merge metadata. When serialized, these two structures get mixed to make the text version of a roster. + + +[[Anchor(RevisionGraph)]] + Revision Graph:: See [#DirectedAcyclicGraph Directed Acyclic Graph]. ============================================================ --- wiki/HistoryBlueSky.moin 8755486b8b434b2ef10e8267edcf4b216f226b91 +++ wiki/HistoryBlueSky.moin 8755486b8b434b2ef10e8267edcf4b216f226b91 @@ -0,0 +1,62 @@ +Space-age things that would be cool to support in our history representation (though not strictly necessary): + += Suturing = + +'''Use case:''' Melding together trees that were separately imported. For instance, PeterSimons (used to?) use monotone to manage his [http://autoconf-archive.cryp.to/ unified autoconf archive] -- there are several sites that collect autoconf macros, and he imports each into a "vendor branch", and then merges them all on top of each other. As each site updates the various macros in random ways, one can continue to propagate them together. + +Should it be undoable? The operation is not simple "split", it is "split into this logical file that went into the suture and that logical file that went into the suture". Very similar issues here as are faced by revival. + +== Merging == + +Not clear how to textual merging -- using a naive weave merge, for instance, there are no benefits to suturing at the file level, you also have to suture at the line level in some more complex way. But, directory suturing may be possible now. + +Adds conflict cases to merge -- there may be arbitrarily many different names that a given item wants to take on (as opposed to at most 2, currently). (Imagine one side of the merge suturing n different files together, while the other side of the merge renames each of those files; after merging, every one of the n different names is a possible winner for the sutured file.) + +May add more conflict cases -- for instance, if one side of a merge sutures files A and B, while the other side deletes only A, what should happen? With death as irrevocable, there is at least an unambiguous answer to this -- the suture includes A, A is totally dead, so kill the suture. If death is revocable, then this becomes much more unclear -- what if the other side deleted A and also deleted and then revived B? + +If it is undoable, rather than irrevocable, then we need some way to merge suture states. Not clear how to do this. Random idea: model each pair-wise potential suture as a boolean, false means not currently sutured, true means currently sutured. Scalar merge these booleans. Problem: suturing is actually about the transitive closure of such pair-wise relations... + += File/directory revival = + +Important for reversion, undoing changes of all kinds + +'''Use case:''' accidentally deleted something on a branch, need to revive it so future merges work right + +'''Use case (same as above, really):''' merged from a vendor branch, pruned parts that don't need. Later start needing them again; need to revive. + +'''Use case:''' Allow propagating changes in *both* directions across a merge_into_dir. + * merge branch A into directory subdir/ in branch B + * propagate A -> B to keep B up-to-date + * edit something under subdir/ in B, and decide that it needs to be propagated upstream + * propagate B -> A (the merged rev will see everything in B not under subdir/ get deleted) + * continue the normal A -> B propagates (what was deleted in the previous step should be revived here) + +For this to work, propagate would also have to manually fiddle the merge to not use the standard merger on the renamed root nodes, as well as playing with delete/revive. + +(Basically, have propagate use the presence of root renames as a flag to merge (live, dead) as either (delete, ...) or (..., revive).) + +This should allow similar behavior to nested CVS checkouts as requested in [https://savannah.nongnu.org/bugs/index.php?func=detailitem&item_id=13409 Bug 13409] (although it'd be branch-wide instead of just a specific workspace). + +== Merging == + +Treat life as a scalar boolean, merge like any other scalr. + +== Problems == + +How do we specify what entity is being revived? + +Interacts with suturing (because suturing effects entity identity model). + +Interacts with partial pull (because we may need to determine identity of two revivals of an object that we don't actually have a record of). + +May interact with content merging (because in weave merges for example, need to figure out how lines of new version correspond to lines in all "leaf" versions) + += Splitting = + +The conceptual inverse of suturing (though not, as noted above, the actual literal inverse). This is more like "copy" -- the inverse of a copy is a suture. + +Copies have all sorts of weird properties. You have to ask whether they are asymmetrical, for instance. + +'''Use case:''' I want to add a new gcc backend. However, I find the prospect of writing such a thing from scratch terrifying, so I copy another backend and then modify it. I consider it kind of nice that things like "annotate" work smoothly across the copy (though there is some debate about this, because the guys who wrote the brand-X backend have no real desire to be hassled about the new brand-Y backend). As for merging, the brand-X guys should not be hassled about my changes. However, I may wish to merge in changes made to the brand-X backend. + +'''Use case:''' I'm refactoring, and I split one file into two parts. I'd like "annotate" etc. to follow the history in both directions. I'd also like edits to the pre-split file to be automatically applied to the post-splits files when I merge. ============================================================ --- wiki/Hosting.moin f13962875f0a802cf96b0190b44fba8db85f78d0 +++ wiki/Hosting.moin f13962875f0a802cf96b0190b44fba8db85f78d0 @@ -0,0 +1,5 @@ +You can easily host monotone anywhere you can run a daemon. With the "dumb server" support, you don't even need that -- all that is required is standard web hosting -- but this option is more experimental, and needs more work to be fully supported (want to help?). + +If those two options don't work for you, here are some other options to consider: + * http://mtn-host.prjek.net provides '''free public monotone hosting''', with an easy-to-use web management interface. + * Virtual servers quite capable of running monotone are easily available in the $15-20/month USD range -- for example, [http://prgmr.com/xen/ here], [http://www.tektonic.net/vds.php?op=budget_plans here], [http://www.budgetdedicated.com/ here], or [http://www.slicehost.com/ here] (we have not used any of these services, and this is not a particular recommendation -- if you have recommendations, by all means add them here). If going this route, note that the monotone server can be a bit cpu and memory hungry -- we're working on reducing this, but in the mean time, you probably don't want the very smallest servers available. ============================================================ --- wiki/HugoMills.moin 505ee089bf7588807478d05b5e3daea0b28ceab4 +++ wiki/HugoMills.moin 505ee089bf7588807478d05b5e3daea0b28ceab4 @@ -0,0 +1,10 @@ +#format wiki +#language en +== Your Name == + +Email: [[MailTo(hugoATcarfaxDOTorgDOTuk)]] + +See [[http://www.carfax.org.uk/]] + +---- +CategoryHomepage ============================================================ --- wiki/I18nL10n.moin 68d2b64f1651c8e1036990aecaaf2b3fc361dcd1 +++ wiki/I18nL10n.moin 68d2b64f1651c8e1036990aecaaf2b3fc361dcd1 @@ -0,0 +1,55 @@ +i18n and l10n are non-trivial; more so for monotone than for most apps. + += Character sets = + +Firstly, we have to deal with at least 3 logically distinct charsets + * the user's display/entry charset + * the user's filesystem charset + * utf8, for our internal storage + +On most POSIX systems, the user's display/entry charset and the user's filesystem's charset are identical. On OS X, the filesystem charset is always unicode (though this is very poorly documented, so I'm just assuming it's utf8), and the user's display/entry charset ''may'' differ -- though I do not know if it ever does in practice. I don't know how things work on Win32, but I've heard that it's as bad as you might fear. + +To make this more interesting, `gettext` returns strings in the user's display/entry charset. While technically you ''can'' tell `gettext` to instead return strings in utf8 (see `bind_textdomain_codeset`) -- perhaps because you think this will let you use a simple strategy, where internal data is always utf8 and you convert when talking to the outside world -- this runs into some issues in practice. In particular, `strerror` will continue to return errors in the user's charset (you can work around this by converting back manually; glib's `g_strerror` does this), popt will continue to use the local charset, and for extra fun, if a charset conversion error occurs, we have no way to report it, because we cannot print to the terminal without doing charset conversion. I tried doing this once and gave up -- if anyone wants to try again, the code around 2561d8175fafe1ce3718f1eb71112012892c5d21 will be useful. + +The net result is that one needs to keep track, for basically every string in the system, which of the above charsets it is in, and do conversions appropriately. The best way to do this, obviously, is with the type system; we have a few vocab.cc types for this, but they are not used systematically. Much more work is needed; for instance, a real solution probably includes a modified formatter object that knows how to do charset conversion when doing %s replacement, and refuses to accept bare std::string's. + += Bugs = + +There are a bunch of places where we do not do proper conversion. Pretty much every F() call is suspect, but there are some particular places marked in the source with BUG, where njs happened to notice things while he was going through. Here are some more notable ones: + +== Filesystem reading == + +The tree walker does not convert from the filesystem charset to utf8, but it should. + +== Data validation == + +/!\ `file_path`'s verifier should validate that it is handling valid utf8. We do not currently do this. + +I don't know if we make sure that changelog comments are appropriately converted. We may not. + +== Display == + +There are various places -- commands.cc's lining up of commands, tickers lining up numbers with labels, tickers truncating themselves at the edge of the terminal to avoid staircasing, etc. -- where we need to know the display width of characters. + +This is an interesting question, because not all characters take up the same amount of space, even on monospace terminals: see http://www.unicode.org/reports/tr11/ + +I believe that the UNIX98 functions `wcwidth`, `wcswidth`, and ilk, know how to deal with this. They are not necessarily available everywhere. Right now, we simply use a few lines of direct coding to count up utf8 characters, which is wrong even if we are dealing with utf8, and we probably can't count on that anyway. + +== stringprep/idna/... == + +We should probably audit everything dealing with stringprep/idna/etc. For instance, there is wackiness in handling i18n'ed key names, because email addresses have hostnames in them and i18n hostnames are wacky. + +== Composition/decomposition == + +It is possible that there are filesystems which somehow normalize unicode strings. (E.g., [http://developer.apple.com/technotes/tn/tn1150.html#UnicodeSubtleties HFS+ on OS X] probably does.) These raise issues similar to CaseInsensitiveFilesystems, i.e., any form of normalization can cause paths that looked different on one system to look the same on another. In fact, [http://svn.haxx.se/users/archive-2005-12/0381.shtml SVN has encountered this issue in practice]. + +Other useful OS X links: + * [http://developer.apple.com/qa/qa2001/qa1235.html Converting to Precomposed Unicode] + * [http://lists.apple.com/archives/unix-porting/2002/Mar/threads.html#00147 filesystem encodings thread on Apple's user-porting list] ("The BSD-level interface to the file system uses canonically decomposed UTF-8.") + * [http://developer.apple.com/qa/qa2001/qa1173.html Text encodings in VFS] + +The Unicode Consortium has an article on [http://www.unicode.org/unicode/reports/tr15/index.html normalization forms] and a somewhat related article on [http://www.unicode.org/reports/tr36/ security considerations]. + += File content = + +The current system for converting charsets of versioned files, which is hook-based, is not so great. We should probably do something involving attrs instead. ============================================================ --- wiki/IPv6.moin 5c8384ba7aecb04feff53eb8ea9791b14bfadd61 +++ wiki/IPv6.moin 5c8384ba7aecb04feff53eb8ea9791b14bfadd61 @@ -0,0 +1,10 @@ +IPv6 is a bit tricky. + += Known problems = + +If a system does not have IPv6 support, then the default attempt to bind to all interfaces fails. + +Binding to a host name may also fail. Or this may be an artifact of testing. + * Was solved in Version 0.27 (base revision: 341e4a18c594cec49896fa97bd4e74de7bee5827) + +We need a way to test this stuff on old systems! The current testsuite always binds to 127.0.0.1, which does not catch either of the above bugs. However, having monotone open a public port during the test run is highly suboptimal... ============================================================ --- wiki/InterfacesFrontendsAndTools.moin 9d842ffbb7c7c1a76eba9a74436614bc7fb392fc +++ wiki/InterfacesFrontendsAndTools.moin 9d842ffbb7c7c1a76eba9a74436614bc7fb392fc @@ -0,0 +1,75 @@ += Other programs that work with monotone -- interfaces, frontends and tools = + +== interfaces and tools == + + * '''[http://oandrieu.nerim.net/monotone-viz/ monotone-viz]''': [http://gtk.org GTK+] app for browsing and visualizing history + * Emacs integration: + * '''monotone.el''': In `contrib/` directory of monotone's source tree. [http://viewmtn.angrygoats.net/branch/head/file/net.venge.monotone/contrib/monotone.el Latest version] (via viewmtn). + * [http://download.gna.org/dvc/ DVC] (see also [http://gna.org/projects/dvc DVC]) is a project to create a generic library for fancy Emacs interfaces to modern version control systems. DVC includes monotone support. + * '''[http://grahame.angrygoats.net/viewmtn.shtml viewmtn]''': a web interface to a monotone repository. + * As noted below, development of a trac plugin is ongoing: [http://tracmtn.1erlei.de/ TracMtn]. + * '''[http://mtn-host.prjek.net/projects/mtsh/ mtsh]''': GTK+ wrapper for monotone focusing on working copy operations -- add, drop, revert, rename, commit, update, diff, and browsing. Has a mechanism for per-file commit comments. ''(This is a bit old and very much unmaintained.)'' + * '''Usher''': A server manager that can be used to serve several projects on the same IP/port, starting and stopping servers as needed. In branch `net.venge.monotone.contrib.usher`. + * '''[http://meld.sf.net meld]''': a general diff, merge, and history browsing tool written in [http://python.org Python] for [http://gnome.org Gnome]. Has monotone support since 1.1.3. + * '''shell completion''': monotone ships with completion scripts for both bash and zsh, in the `contrib/` directory of monotone's source tree. Latest versions for [http://viewmtn.angrygoats.net/fileinbranch.psp?branch=net.venge.monotone&path=contrib/monotone.bash_completion bash] and [http://viewmtn.angrygoats.net/fileinbranch.psp?branch=net.venge.monotone&path=contrib/monotone.zsh_completion zsh] (via viewmtn). + * "'''dumb server'''" support, for publishing repositories via ordinary ftp/http/sftp/local filesystem: in branch [http://viewmtn.angrygoats.net/branch/changes/net.venge.monotone.dumb]. + * '''[http://www.midwinter.com/~lch/programming/m7/ m7]''': Experimental drop-in command-line wrapper for monotone. Adds simple local version numbers (no longer using certs) and an enhanced annotate front-end. + * '''[http://www.highscore.de/monotree/ monotree]''': java app for browsing and visualizing history; more portable than monotone-viz. In branch `net.venge.monotone.contrib.monotree`. + * '''[http://rscm.rubyforge.org/classes/RSCM/Monotone.html RSCM::Monotone]''': a [http://www.ruby-lang.org/ Ruby] interface to monotone. + * '''monotone-import.pl''': A script to ease importing other people's source distributions into a monotone branch, useful for tracking "vendor branches" and the like. In `contrib/` directory of monotone's source tree. [http://viewmtn.angrygoats.net/fileinbranch.psp?branch=net.venge.monotone&path=contrib/monotone-import.pl Latest version] (via viewmtn). + * '''monotone-notify.pl''': A script to watch a monotone repository and, for example, send emails on commits. In `contrib/` directory of monotone's source tree. [http://viewmtn.angrygoats.net/fileinbranch.psp?branch=net.venge.monotone&path=contrib/monotone-notify.pl Latest version] (via viewmtn). + * '''ciabot_monotone.py''': A notification script for [http://cia.navi.cx CIA]. In `contrib/` directory of monotone's source tree. [http://viewmtn.angrygoats.net/fileinbranch.psp?branch=net.venge.monotone&path=contrib/ciabot_monotone.py Latest version] (via viewmtn). + * Script for '''importing maildir-format mailboxes''' to monotone, for offline reading and syncing: [http://lists.gnu.org/archive/html/monotone-devel/2005-09/msg00234.html on the list] + * '''[http://www.wireshark.org Wireshark]''' (new fork) and '''[http://www.ethereal.com Ethereal]''' (original, possibly inactive branch): a fantastic network traffic analyzer, that has support for decoding monotone's 'netsync' protocol. + * '''[http://guitone.thomaskeller.biz guitone]''': A Qt-based, cross-platform frontend for monotone, in early stage [http://viewmtn.angrygoats.net/branch/head/browse/net.venge.monotone.guitone Latest version (via viewmtn)]. + * '''[http://aleph0.info/apso/ Apso]''': A system for encrypting version control system repositories/databases (currently a prototype; the first version control system supported is Monotone). + * '''[http://www.highscore.de/monotree/ Monotree]''': A .NET based viewer for monotone's database (does not require to have monotone installed as it loads monotone's database directly and creates a report). + * '''[http://ikiwiki.info/ Ikiwiki]''' is a wiki that can use a revision control system, and in particular [http://ikiwiki.info/rcs/monotone/ monotone], as a backend. As Monotone is distributed, Ikiwiki becomes distributed. Ikiwiki also has a bug tracking plugin that then allows distributed bug tracking. + +== converting to monotone from other systems == + + CVS:: no external tool required or recommended; simply use monotone's `cvs_import` command. See ["MonotoneAndCVS"]. + Subversion, Darcs, many others:: '''[http://progetti.arstecnica.it/tailor Tailor]''' is an any-to-any version control system converter, with support for most free VCSes. Note that as of July 2007, histories are linearized on the timestamp (so don't expect it to losslessly convert between systems with DAG histories, like monotone/git/mercurial/bzr, for instance). + bitkeeper:: A patch and set of scripts for lossless BK->monotone conversion is available on the mailing list: http://lists.gnu.org/archive/html/monotone-devel/2006-01/msg00314.html + +== Integrated development environments == + + * '''[http://pida.berlios.de/ PIDA]''': Integrated development environment supporting Monotone (among others) + +== merge tools == + +When you do a merge in monotone, and run into conflicts, it will automatically start up a nice +graphical merger for you to resolve them in. These mergers (and possibly others) are supported +out of the box. + + * '''[http://kdiff3.sourceforge.net/ KDiff3]''': Supported on Unix, Windows, OS X. ('''recommended''') + * '''[http://furius.ca/xxdiff/ xxdiff]''': Supported on Unix, maybe OS X. ('''recommended''') + * '''[http://tortoisesvn.tigris.org/ TortoiseMerge]''': Supported on Windows. This is a stand-alone merge program that happens to be packaged with TortoiseSVN -- so you have to install the whole TortoiseSVN package, but you will only use TortoiseMerge. ('''recommended''') + * '''[http://www.gnu.org/software/emacs/emacs.html emacs]'''/'''[http://www.xemacs.org/ xemacs]''': via [http://www.delorie.com/gnu/docs/emacs/ediff.html Ediff]. Supported pretty much everywhere. + * '''[http://www.vim.org/ vim]''': via vimdiff. Supported pretty much everywhere. + * '''[http://meld.sourceforge.net/ meld]''': Supported on Unix (Gnome). + * FileMerge.app: Part of the OS X Developer Tools package. Supported on OS X. + +[[Anchor(wishes)]] += Other programs that *should* be taught to work with monotone, but haven't been = + + * [http://trac.edgewall.com trac] is a popular integrated history browser/wiki/bug tracker, which has very recently grown a plugin interface that lets it work with VCSes besides subversion. The right place to start is probably the [http://projects.edgewall.com/trac/wiki/TracMercurial Mercurial plugin], since mercurial uses the basic monotone history model. (python) + * Development of a trac plugin has already been started, see the [http://viewmtn.angrygoats.net/branch.psp?branch=net.venge.monotone.trac-plugin trac-plugin branch] or [http://tracmtn.1erlei.de/ TracMtn]. + * "[http://repo.or.cz/w/hgct.git Commit Tool] or (h)gct is a GUI enabled commit tool...It allows the user to view diffs, select which files to committed (or ignored / reverted) write commit messages and perform the commit itself." (python) + * [http://eclipse.org Eclipse] -- a well known, extremely pluggable IDE. Might be useful to look at the [http://eclipsedarcs.org/doku.php Darcs plugin] or [http://www.eclipse.org/community/team.php other] existing VCS plugins. (java) + * [http://www.jetbrains.com IntelliJ IDEA] is a commercial java IDE with strong support for analysis and refactoring, and an open plugin API allowing integration of new version control systems. Derek Scherger [http://www.mail-archive.com/address@hidden/msg05443.html claims] to have fiddled with a monotone plugin. Someone on the [http://intellij.org IntelliJ Community Wiki] claimed to be developing a monotone plugin, but did not want to publish the source yet. + * "git-cvsserver": some crazy people have written a perl script that implements a usable subset of cvs's network protocol, backed against a git repo. the mapping is bidirectional, so people who like cvs, can do both checkout and ''commit'' using cvs, and it shows up in git. There is no reason this could not be taught to work against a monotone backend. "git clone http://mirrors.catalyst.net.nz/git/gitcvs.git/" + * Xcode, the Apple Mac OS X IDE + * ''your request here'' + += Other programs that don't exist at all, but if they did they would make using monotone just that much more awesome = + + * tools to manage code reviews, integration workflows, and such things + * one possibly relevant thing: vim plugin for doing code reviews: http://www.vim.org/scripts/script.php?script_id=1563 + * a cross-platform GUI monotone interface (probably using Qt, since that seems to be the best way to make sane cross-platform interfaces these days?) (GTKmm is really nice IMO, would be worth a look if someone went ahead on this) (both Qt and GTKmm add several megabtytes of bloat on OS X; try wxWindows or FLTK instead) + * The work on a cross-platform GUI has already started, see http://guitone.thomaskeller.biz or mtn://venge.net/net.venge.monotone.guitone + * "Tortoise Monotone" -- a windows interface to monotone, integrated with the file explorer. This approach works ''very'' well for subversion... + * `mtnpatch`, a small, standalone, slightly smarter version/wrapper of `patch(1)` that understands and can apply the additional cset operations (eg, `drop` and `rename`) listed in `mtn diff` comments. Useful for end-users tracking monotone sources without actually using monotone or a db. Bonus points for a `mtnfollow` that combines this patch tool with a web client to fetch diffs as needed from viewmtn, and keeps a `_MTN` directory up to date so its easy for a user to switch to using full monotone once they need it (eg, for local changes). + * A Visual Studio plugin for Monotone. + + * ''your wished-for tool here'' ============================================================ --- wiki/JackLloyd.moin 871bb9517356b15024d2d785a7cb2994d87cb9a2 +++ wiki/JackLloyd.moin 871bb9517356b15024d2d785a7cb2994d87cb9a2 @@ -0,0 +1,10 @@ +== Jack Lloyd == + +Wrote/maintains Botan. Used to work on OpenCM, which was somewhat Monotone-like. + +Email: [[MailTo(address@hidden)]] [[BR]] +Webpage: http://www.randombit.net/ [[BR]] +AIM: cykl01d + +---- +CategoryHomepage ============================================================ --- wiki/JustinPatrin.moin fc157c5c6a1ddddcdf5b3d116d1fa4ab6855dcf8 +++ wiki/JustinPatrin.moin fc157c5c6a1ddddcdf5b3d116d1fa4ab6855dcf8 @@ -0,0 +1,4 @@ +A user of monotone via the [http://openembedded.org OpenEmbedded] project. Started developing on monotone at the 2007 summit at Google with the net.venge.monotone.ssh-agent branch (see ["MonotoneAndSSHAgent"]). + +For more info: +http://justin.patrin.info/ ============================================================ --- wiki/KeystoreFiles.moin 9ca54de5971395feff06791195b07f3d82749565 +++ wiki/KeystoreFiles.moin 9ca54de5971395feff06791195b07f3d82749565 @@ -0,0 +1,8 @@ +I think the keystore, ~/.monotone/keys, could be more usable. (And this is an area where usability is important for security.) + +Problems: + * It is not obvious how to find one's public key + * It is not obvious that ~/.monotone/keys/ contains private keys (recently a very smart person sent me his private key accidentally...) + * We would like to allow passphrase-less keys, but it should be obvious when you have such a key + +Proposed solution: stick extra tags on the end of files we write to the keystore. At read time, we can do just like we do now, and just read whatever files are there and suck out any keypair packets. At write time, we peek at the key we're going to write, and name the file like -, where is either "PRIVATE" or "PRIVATE,NO-PASSPHRASE", so people are always clear on what exactly they have when they look in the key dir. So I might have ~/.monotone/keys/address@hidden (We could also write out a pubkey packet for convenience, and stick that in a file with -PUBLIC stuck on the end.) ============================================================ --- wiki/LineEndingMunging.moin 227520a6a479c07721cd8753ada4a2a806ae7c58 +++ wiki/LineEndingMunging.moin 227520a6a479c07721cd8753ada4a2a806ae7c58 @@ -0,0 +1,63 @@ +We have to munge line endings in various ways. This is a sad fact, but it seems unavaoidable, so how should we minimize the pain? + +The goal ''is not'' to come up with a perfect solution that can handle every single situation we can possibly conceive of, plus a large number we can't conceive of. The goal ''is'' to come up with the minimal solution that is correct and will not feel minimal to users. + +Discussion links: + * http://thread.gmane.org/gmane.comp.version-control.monotone.devel/5881 + * http://colabti.de/irclogger/irclogger_log/monotone?date=2006-02-02,Thu&sel=53#l104 + * http://thread.gmane.org/gmane.comp.version-control.monotone.devel/5964 + * http://thread.gmane.org/gmane.comp.version-control.monotone.devel/9231 + * http://thread.gmane.org/gmane.comp.version-control.monotone.devel/9304 + += In the Workspace = + +== Current implementation == + +We currently control this stuff with a hook. This is manifestly broken. It should be controlled per-file with attrs (I think the only reason it isn't is that attrs didn't exist back then). + +== Other implementations == + +=== Subversion === + +Subversion has definitely put thought into their rules here. It's worth reading their [http://svnbook.red-bean.com/en/1.1/ch07s02.html#svn-ch-7-sect-2.3.5 docs]. Basically, the rules are: + * you have to opt-in to line end munging on a file-by-file basis + * files can be specified to be always-LF, always-CRLF, always-CR, or always-native. + * one can use a server-side hook to require that all files have a mime type, and that all files with text/* mime types have an explicit eol style. This is recommended, and the svn people do this on their own repo. + * individual users can use the "autoprops" functionality to give a list of filename patterns and the eol-style that they want automatically applied to them + * handling of edge cases is a bit weird -- their convert-to-