|
Size: 28864
Comment:
|
← Revision 35 as of 2013-12-28 09:13:03 ⇥
Size: 24
Comment: cuckoo egg deleted
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| = Průběhová schemata v Mercurialu = V Mercurialu lze realizovat mnoho různých průběhových schemat. V tomto textu se s některými seznámíme, přičemž budeme postupovat od jednodušších ke složitějším. Účelem této pomůcky je usnadnit začátečníkům práci se sledováním verzí (verzování). Použité pojmy nejsou vysvětlovány, neboť existuje řada jiných výtečných textů ([[Základy Mercurialu]] a [[http://hgbook.red-bean.com/read/behind-the-scenes.html|Za kulisami]]), které tak činí. Podrobnější popis se základními pojmy naleznete v tutorialu o používání Mercurialu - CzechTutorial. Opravdu podrobný a velmi čtivý popis Mercurialu obsahuje kniha B. O´Raillyho [[http://hgbook.red-bean.com|Mercurial:The Definitive Guide ]]. <!> Tento průvodce nevyžaduje žádnou předchozí znalost VCS (i když uživatelé Subversion se budou patrně brzo cítit doma). Zkušenosti s konzolou příkazového řádku budou prospěšné, protože CLI budeme používat. = Základní průběhová schemata = == Osamělý vývojář s jednoosou historií == === Popis případu === První průběhové schema je nejsnadnější. Chceme zaznamenávat změny a mít možnost se kdykoliv ke kterékoliv vrátit a prohlédnout si ji. Tento průběh vyžaduje pouze nainstalovaný Mercurial a dostatečná přístupová práva k souborům. === Průběh === Jako první krok bychom měli zadat své jméno. V textovém editoru otevřeme soubor `~/.hgrc`, přidáme sekci ui (user interaction) a zapíšeme jméno, případně s e-mailovou adresou: {{{ [ui] username = Mr. Johnson <hali@beli.cz> }}} Nyní vytvoříme adresář, ve kterém budeme pracovat (včetně složky .hg): {{{ $ hg init baboon }}} Přejdeme do adresáře, vytvoříme nějaké soubory a přidáme je ke sledování: {{{ $ cd baboon $ (vytvoření souborů) $ hg add }}} <!> Můžeme také vstoupit do existujícího adresáře se soubory a tam vytvořit složku (repozitář) .hg: {{{ $ cd project $ hg init }}} Případně můžeme přidat ke sledování jenom určité soubory místo všech souborů v adresáři. Následujícím příkazem například přikážeme sledování souborů `file10, file11` a `file12`: {{{ $ hg add file0* }}} Přidané soubory se staly kandidáty pro registraci. Vlastní zápis změn do repozitáře provádíme jejich předáním příkazem 'commit': {{{ $ hg commit }}} Vyskočí textový editor a žádá si zápis komentáře komitu. Po uložení a zavření editoru máme změny předané. <!> Komentář komitu lze zadat zároveň s jeho příkazem (zde zkráceným): {{{ $ hg ci -m "Komentář" }}} Přítomnost nekomitovaných změn v pracovním adresáři zjistíme příkazem: {{{ $ hg status }}} případně rozdíl mezi dvěmi verzemi souboru: {{{ $ hg diff }}} Při přemístění a kopírování souborů pomocí příkazů Mercurialu nemusíme změny "uvádět na kandidátskou listinu" příkazy `hg add`, `hg remove` nebo `hg addremove`. Nezapomeneme však předat změny repozitáři, to jest provést příkaz '''commit''': {{{ $ hg cp orig kopie $ hg ci -m "stručný komentář" $ hg mv orig sloha/rupie # přemístit lze jen uvnitř kořenového adresáře $ hg ci -m "sloha je název adresáře" }}} Máme nyní dva nové soubory 'kopie' a 'rupie' a Mercurial o nich ví. Výpis seznamu všech zaznamenaných změn vyvoláme příkazem: {{{ $ hg log }}} Informace o changesetu (revizi) obsahuje ID, jméno komitenta, datum a čas komitu a komentář. Pokud nás zajímá jenom určitá revize, použijeme přepínač ''-r'' (--revision). Aby se nám také zobrazil diff určené revize, přidáme přepínač ''-p'' (--patch): {{{ $ hg log -p -r 3 }}} == Osamělý vývojář s víceosou historií == === Popis případu === Druhé průběhové schema je stále velmi jednoduché: jste sám a chcete aby Mercurial zaznamenával vaše změny, přičemž je možné, že se budete chtít někdy vrátit ke starší revizi a dodatečně ji upravit. === Průběh === Otevření nového projektu, případně založení nového repozitáře, případně další práci v pracovním adresáři provádíme známým způsobem: {{{ $ hg init projekt $ cd projekt $ (přidáme soubory) $ hg add # zařadíme je ke sledování $ (provedeme nějaké změny) $ hg diff # prohlédneme si je $ hg ci -m "zápecí" # předáme je repozitáři $ hg cp copak kampak # kopírujeme soubory či složky $ hg mv copak kampak # přemístíme soubory či složky $ hg ci -m "párátko" $ hg log # prohlédneme si historii }}} __Návrat ke starší revizi__ Nyní jsme v situaci, že se potřebujeme vrátit ke starší revizi (např. 3) a opravit tam přehlédnutou chybu. Ke stavu revize 3 potřebujeme vrátit také pracovní adresář: {{{ $ hg update 3 }}} Že tam skutečně jsme, se přesvědčíme příkazem: {{{ $ hg identify -n # dostaneme pořadové číslo revize }}} <!> Příkaz ''identify'' bez přepínače nám vrátí zkrácený tvar ID. Na rozdíl od pořadového čísla revize, které pro tentýž changeset může být v každém repozitáři jiné, se toto číslo nemění. Pořadové číslování revizí začíná nulou. Je-li aktuální poslední revize, ''hg identify -n'' vrátí ''-1''. Aktualizovat k poslední revizi můžeme (zkráceně) příkazem: {{{ $ hg up tip }}} __Oprava starších chyb__ Opravu chyby ve starší revizi provedeme tak, že se do ní vrátíme a chybu opravíme. Tím ale vytvoříme v repozitáři další čelo (head), které musíme sloučit s čelem stávajícím: {{{ $ hg update 3 $ (opravíme chybu) $ hg commit }}} Oprava chyby je tedy předána historii. Ještě sloučíme čela: {{{ $ hg merge }}} Pokud by se při sloučení vyskytl problém, použijeme příkaz ''hg resolve'' - tak, jak jsme beztoho v takovém případě programem vybízeni. Nejprve dáme vypsat seznam konfliktních souborů: {{{ $ hg resolve --list }}} Potom je jeden po druhém řešíme. Příkaz ''resolve'' se opět pokusí o sloučení: {{{ $ hg resolve konfliktní_soubor (případně upravíme konflikt ručně) }}} Upravený soubor označíme jako řešený {{{ $ hg resolve --mark conflicting_file }}} Jakmile vyřešíme všechny konflikty, provedeme ''commit''! Ten ostatně provedeme i když se žádné konflikty nevyskytly. {{{ $ hg commit }}} V této chvíli máme opravu sloučenou s ostatní naší prací, ve které můžeme pokračovat. Zaznamenaná historie nám jasně ukazuje, kde chyba vznikla a kdy byla opravena. <!> Když opravíme chybu souboru ve starší revizi a v nějaké pozdější revizi byl tento soubor kopírován nebo přemístěn, bude sloučením tato oprava rozšířena do cílových souborů. To je hlavní důvod, proč bychom kopírování a přemísťování souborů uvnitř pracovního adresáře měli provádět pomocí příkazů Mercurialu ''hg cp'' a ''hg mv''. == Oddělený vývoj == === Popis případu === Někdy pracujeme současně na několika procedurách jednoho programu. Chceme-li se vyhnout náhodnému pomíchání nehotových verzí kódu, můžeme vytvořit klony lokálního repozitáře a pracovat na jednotlivých procedurách v jejich vlastních pracovních adresářích. Po dokončení proceduru ''stáhneme (pull)'' zpět do hlavního adresáře a ''sloučíme (merge)'' ji s lokálními změnami. === Průběh === __ Práce v různých klonech__ Nejprve vytvoříme klon a v něm nějaké změny: {{{ $ hg clone baboon makak $ cd makak $ (provedeme změny a komity) }}} Nyní si ověříme, co obdržíme, když provedeme ''pull'' z adresáře makak, podobně jako používáme příkaz ''diff'' před komitem. Příslušný příkaz pro to je ''incoming (příchozí)'': {{{ $ cd ../baboon $ hg incoming ../makak }}} <!> Kdybychom chtěli vidět diffy, použijeme přepínač ''hg incoming --patch'' stejně jako použijeme tento přepínač (''hg log --patch'') při zjišťování změn v repozitáři. </div> Pokud se nám změny zamlouvají, stáhneme je do hlavního adresáře projektu: {{{ $ hg pull ../makak }}} Změny jsme si z adresáře ''makak'' stáhli, ale v adresáři ''baboon'' je zatím nevidíme. Jsou uloženy v systémovém adresáři ''.hg'' (viz [[http://hgbook.red-bean.com/read/behind-the-scenes.html|Za kulisami more information on the store]]). <!> Od této chvíle budeme slovo ''repozitář'' používat pro systémový adresář ''.hg''. Pokud jsme v adresáři ''baboon'' žádné změny neprovedli, stačí nám po stažení změn z adresáře ''makak'' provést pouze ''hg update tip'', to jest aktualizovat pracovní adresář k novému tipu. Je však více než pravděpodobné, že jsme si v ''baboon'' změny provedli; v tom případě je nutné sloučit stažené změny se změnami lokálními: {{{ $ hg merge }}} Pokud jsou konflikty, provedeme ''hg resolve''. Po sloučení musíme provést ''commit'', aby se naše úpravy zapsaly do repozitáře: {{{ $ hg ci -m "připojený makak" }}} Lze provést libovolný počet klonů a nosit je po kapsách na tyčinkách USB. <!> Příkaz ''commit'' musíme zadat i po nekonfliktním sloučení, protože tím tuto změnu zapisujeme do historie. __Odvolání chyb__ Nyní tedy pracujeme současně na různých procedurách, ale čas od času se nám podaří provést špatný komit. Pokud to zjistíme dřív, než provedeme další komit nebo pull, můžeme tuto zmýlenou snadno napravit příkazem ''rollback (odvolat)'': {{{ hg rollback }}} Podle přísloví ''dobrého pomálu'' nelze provést ''rollback'' dvakrát bezprostředně za sebou. <!> Příkaz ''rollback'' lze použít také pro odvolání příkazu ''pull'', pokud jsme poté neprovedli komit. == Sdílení změn == === Popis případu === === Use Case === Now we go one step further: You are no longer alone, and you want to share your changes with others and include their changes. The basic requirement for that is that you have to be able to see the changes of others. Mercurial allows you to do that very easily by including a simple webserver from which you can ''pull'' changes just as you can pull changes from local clones. <div class="note"> Note: There are a few other ways to share changes, though. Instead of using the builtin webserver, you can also send the changes by email or setup a shared repository, to where you ''push'' changes instead of pulling them. We'll cover one of those later. </div> === Workflow === ===== Using the builtin webserver ===== This is the easiest way to quickly share changes. First the one who wants to share his changes creates the webserver $ hg serve Now all others can point their browsers to his IP address (for example 192.168.178.100) at port 8000. They will then see all his history there and can decide if they want to pull his changes. $ firefox http://192.168.178.100:8000 If they decide to include the changes, they just pull from the same URL $ hg pull http://192.168.178.100:8000 At this point you all can work as if you had pulled from a local repository. All the data is now in your individual repositories and you can merge the changes and work with them without needing any connection to the served repository. ===== Sending changes by email ===== Often you won't have direct access to the repository of someone else, be it because he's behind a restrictive firewall, or because you live in different timezones. You might also want to keep your changes confidential and prefer internal email (if you want additional protection, you can also encrypt the emails, for example with [http://gnupg.org GnuPG]). In that case, you can easily export your changes as patches and send them by email. Another reason to send them by email can be that your policy requires manual review of the changes when the other developers are used to reading diffs in emails. I'm sure you can think of more reasons. Sending the changes via email is pretty straightforward with Mercurial. You just ''export'' your changes and attach (or copy paste) it in your email. Your colleagues can then just ''import'' them. First check which changes you want to export $ cd project $ hg log We assume that you want to export changeset 3 and 4 $ hg export 3 > change3.diff $ hg export 4 > change4.diff Now attach them to an email and your colleagues can just run ''import'' on both diffs to get your full changes, including your user information. To be careful, they first ''clone'' their repository to have an integration directory as sandbox $ hg clone project integration $ cd integration $ hg import change3.diff $ hg import change4.diff That's it. They can now test your changes in feature clones. If they accept them, they ''pull'' the changes into the main repository $ cd ../project $ hg pull ../integration <div class="note"> Note: The ''patchbomb'' extension automates the email-sending, but you don't need it for this workflow. </div><div class="note"> Note: You can also send around bundles, which are snippets of your actual history. Just create them via $ hg bundle --base FIRST_REVISION_TO_BUNDLE changes.bundle Others can then get your changes by simply pulling them, as if your bundle were an actual repository $ hg pull path/to/changes.bundle </div> ===== Using a shared repository ===== Sending changes by email might be the easiest way to reach people when you aren't yet part of the regular development team, but it creates additional workload: You have to ''bundle'' the changes, send mails and then ''import'' the bundles manually. Luckily there's an easier way which works quite well: The shared push repository. Till now we transferred all changes either via email or via ''pull''. Now we use another option: pushing. As the name suggests it's just the opposite of pulling: You ''push'' your changes into another repository. But to make use of it, we first need something we can push to. By default ''hg serve'' doesn't allow pushing, since that would be a major security hole. You can allow pushing in the server, but that's no solution when you live in different timezones, so we'll go with another approach here: Using a shared repository, either on an existing shared server or on a service like [http://bitbucket.org BitBucket]. Doing so has a bit higher starting cost and takes a bit longer to explain, but it's well worth the effort spent. If you want to use an existing shared server, you can use ''serve'' there and [http://www.selenic.com/mercurial/wiki/HgWebDirStepByStep#head-746ca383e3a62df34279ec2fca888113497da022 allow pushing]. Also there are some other nice ways to [http://www.selenic.com/mercurial/wiki/MultipleCommitters allow pushing to a Mercurial repository], including simple [http://www.selenic.com/mercurial/wiki/SharedSSH access via SSH]. Otherwise you first need to setup a BitBucket Account. Just signup at [http://bitbucket.org BitBucket]. After signing up (and login) hover your mouse over "Repositories". There click the item at the bottom of the opening dialog which say "Create new". Give it a name and a description. If you want to keep it hidden from the public, select "private" $ firefox http://bitbucket.org Now your repository is created and you see instructions for ''push''ing to it. for that you'll use a command similar to the following (just with a different URL) $ hg push https://bitbucket.org/ArneBab/hello/ (Replace the URL with the URL of your created repository. If your username is "Foo" and your repository is named "bar", the URL will be https://bitbucket.org/Foo/bar/) Mercurial will ask for your BitBucket name and password, then ''push'' your code. Voili?1, your code is online. <div class="note"> Note: You can also [http://bitbucket.org/help/UsingSSH use SSH for pushing to BitBucket]. </div> Now it's time to tell all your colleagues to sign up at BitBucket, too. After that you can click the "Admin" tab of your created repository and add the usernames of your colleagues on the right side under "Permission: Writers". Now they are allowed to ''push'' code to the repository. (If you chose to make the repository private, you'll need to add them to "Permission: Readers", too) If one of you now wants to publish changes, he'll simply ''push'' them to the repository, and all others get them by ''pull''ing. Publish your changes $ hg push https://bitbucket.org/ArneBab/hello/ Pull others changes into your local repository $ hg pull https://bitbucket.org/ArneBab/hello/ People who join you in development can also just ''clone'' this repository, as if one of you were using ''hg serve'' $ hg clone https://bitbucket.org/ArneBab/hello/ hello That local repository will automatically be configured to pull/push from/to the online repository, so new contributors can just use ''hg push'' and ''hg pull'' without an URL. <div class="note"> Note: To make this workflow more scalable, each one of you can have his own BitBucket repository and you can simply ''pull'' from the others repositories. That way you can easily establish workflows in which certain people act as integrators and finally ''push'' checked code to a shared pull repository from which all others pull. </div><div class="note"> Note: You can also use this workflow with a shared server instead of BitBucket, either via SSH or via a shared directory. An example for an SSH URL with Mercurial is be ssh://user@example.com/path/to/repo. When using a shared directory you just push as if the repository in the shared directory were on your local drive. </div> == Summary == Now let's take a step back and look where we are. With the commands you already know, a bit reading of ''hg help <command>'' and some evil script-fu you can already do almost everything you'll ever need to do when working with source code history. So from now on almost everything is convenience, and that's a good thing. First this is good, because it means, that you can now use most of the concepts which are utilized in more complex workflows. Second it aids you, because convenience lets you focus on your task instead of focusing on your tool. It helps you concentrate on the coding itself. Still you can always go back to the basics, if you want to. A short summary of what you can do which can also act as a short check, if you still remember the meaning of the commands. === create a project === $ hg init project $ cd project $ (add some files) $ hg add $ hg commit (enter the commit message) === do nonlinear development === $ (do some changes) $ hg commit (enter the commit message) $ hg update 0 $ (do some changes) $ hg commit (enter the commit message) $ hg merge $ (optionally hg resolve) $ hg commit (enter the commit message) === use feature clones === $ cd .. $ hg clone project feature1 $ cd feature1 $ (do some changes) $ hg commit (enter the commit message) $ cd ../project $ hg pull ../feature1 === share your repository via the integrated webserver === $ hg serve & $ cd .. $ hg clone http://127.0.0.1:8000 project-clone === export changes to files === $ cd project-clone $ (do some changes) $ hg commit (enter the commit message) $ hg export tip > ../changes.diff === import changes from files === $ cd ../project $ hg import ../changes.diff === pull changes from a served repository (hg serve still runs on project) === $ cd ../feature1 $ hg pull http://127.0.0.1:8000 === Use shared repositories on BitBucket === $ (setup bitbucket repo) $ hg push https://bitbucket.org/USER/REPO (enter name and password in the prompt) $ hg pull https://bitbucket.org/USER/REPO Let's move on towards useful features and a bit more advanced workflows. = Advanced workflows = == Backing out bad revisions == === Use Case === When you routinely pull code from others, it can happen that you overlook some bad change. As soon as others pull that change from you, you have little chance to get completely rid of it. To resolve that problem, Mercurial offers you the ''backout'' command. Backing out a change means, that you tell Mercurial to create a commit which reverses the bad change. That way you don't get rid of the bad code in history, but you can remove it from new revisions. <div class="note"> Note: The basic commands don't directly rewrite history. If you want to do that, you need to activate some of the extensions which are shipped with mercurial. We'll come to that later on. </div> === Workflow === Let's assume the bad change was revision 3, and you already have one more revision in your repository. To remove the bad code, you can just ''backout'' of it. This creates a new change which reverses the bad change. After backing out, you can then merge that new change into the current code. $ hg backout 3 $ hg merge (potentially resolve conflicts) $ hg commit (enter commit message. For example: "merged backout") That's it. You reversed the bad change. It's still recorded that it was once there (following the principle "don't rewrite history, if it's not really necessary"), but it doesn't affect future code anymore. == Collaborative feature development == Now that you can share changes and reverse them if necessary, you can go one step further: Using Mercurial to help in coordinating the coding. The first part is an easy way to develop features together, without requiring every developer to keep track of several feature clones. === Use Case === When you want to split your development into several features, you need to keep track of who works on which feature and where to get which changes. Mercurial makes this easy for you by providing named branches. They are a part of the main repository, so they are available to everyone involved. At the same time, changes committed on a certain branch don't get mixed with the changes in the default branch, so features are kept separate, until they get merged into the default branch. <div class="note"> Note: Cloning a repository always puts you onto the default branch at first. </div> === Workflow === When someone in your group wants to start coding on a feature without disturbing the others, he can create a named branch and commit there. When someone else wants to join in, he just updates to the branch and commits away. As soon as the feature is finished, someone merges the named branch into the default branch. ===== Working in a named branch ===== Create the branch $ hg branch feature1 (do some changes) $ hg commit (write commit message) Update into the branch and work in it $ hg update feature1 (do some changes) $ hg commit (write commit message) Now you can ''commit'', ''pull'', ''push'' and ''merge'' (and anything else) as if you were working in a separate repository. If the history of the named branch is linear and you call "hg merge", Mercurial asks you to specify an explicit revision, since the branch in which you work doesn't have anything to merge. ===== Merge the named branch ===== When you finished the feature, you ''merge'' the branch back into the default branch. $ hg update default $ hg merge feature1 $ hg commit (write commit message) And that's it. Now you can easily keep features separate without unnecessary bookkeeping. <div class="note"> Note: Named branches stay in history as permanent record after you finished your work. If you don't like having that record in your history, please have a look at some of the advanced [http://www.selenic.com/mercurial/wiki/Workflows workflows]. </div> == Tagging revisions == === Use Case === Since you can now code separate features more easily, you might want to mark certain revisions as fit for consumption (or similar). For example you might want to mark releases, or just mark off revisions as reviewed. For this Mercurial offers tags. Tags add a name to a revision and are part of the history. You can tag a change years after it was committed. The tag includes the information when it was added, and tags can be pulled, pushed and merged just like any other committed change. <div class="note"> Note: A tag must not contain the char ":", since that char is used for specifying multiple revisions - see "hg help revisions". </div><div class="note"> Note: To securely mark a revision, you can use the [http://www.selenic.com/mercurial/wiki/GpgExtension gpg extension] to sign the tag. </div> === Workflow === Let's assume you want to give revision 3 the name "v0.1". Add the tag $ hg tag -r 3 v0.1 See all tags $ hg tags When you look at the log you'll now see a line in changeset 3 which marks the Tag. If someone wants to ''update'' to the tagged revision, he can just use the name of your tag $ hg update v0.1 Now he'll be at the tagged revision and can work from there. == Removing history == === Use Case === At times you will have changes in your repository, which you really don't want in it. There are many advanced options for removing these, and most of them use great extensions ([http://www.selenic.com/mercurial/wiki/MqExtension Mercurial Queues] is the most often used one), but in this basic guide, we'll solve the problem with just the commands we already learned. But we'll use an option to clone which we didn't yet use. This workflow becomes inconvenient when you need to remove changes, which are buried below many new changes. If you spot the bad changes early enough, you can get rid of them without too much effort, though. === Workflow === Let's assume you want to get rid of revision 2 and the highest revision is 3. The first step is to use the "--rev" option to ''clone''<nowiki>: Create a clone which only contains the changes up to the specified revision. Since you want to keep revision 1, you only clone up to that</nowiki> $ hg clone -r 1 project stripped Now you can ''export'' the change 3 from the original repository (project) and ''import'' it into the stripped one $ cd project $ hg export 3 > ../changes.diff $ cd ../stripped $ hg import ../changes.diff If a part of the changes couldn't be applied, you'll see that part in *.rej files. If you have *.rej files, you'll have to include or discard changes by hand $ cat *.rej (apply changes by hand) $ hg commit (write commit message) That's it. ''hg export'' also includes the commit message, date, committer and similar metadata, so you are already done. <div class="note"> Note: removing history will change the revision IDs of revisions after the removed one, and if you pull from someone else who still has the revision you removed, you will pull the removed parts again. That's why rewriting history should most times only be done for changes which you didn't yet publicise. </div> == Summary == So now you can work with Mercurial in private, and also share your changes in a multitude of ways. Additionally you can remove bad changes, either by creating a change in the repository which reverses the original change, or by really rewriting history, so it looks like the change never occurred. And you can separate the work on features in a single repository by using named branches and add tags to revisions which are visible markers for others and can be used to update to the tagged revisions. With this we can conclude our practical guide. = More Complex Workflows = If you now want to check some more complex workflows, please have a look at the general [http://selenic.com/mercurial/wiki/Workflows workflows wikipage]. To deepen your understanding, you should also check the [http://mercurial.selenic.com/wiki/UnderstandingMercurial basic concept overview]. Have fun with Mercurial! *PS: This guide is licensed under the [http://gnu.org/licenses/gpl-2.0.html GPLv2]* *PPS: Written by Arne Babenhauserheide, edited by David Soria Parra, Nicolas Dumazet and Steve Losh. Conversion from HTML http://labs.seapine.com/htmltowiki.cgi* |
Temporarily empty page |
Temporarily empty page