|
Size: 13952
Comment:
|
← Revision 41 as of 2012-10-25 22:15:49 ⇥
Size: 0
Comment: Belongs on Eigen's wiki, not ours
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 1: | Line 1: |
| = Mercurial = [[http://hg-scm.org|Mercurial]], známý též jako '''hg''', je nástroj pro správu verzí (source-control management - SCM) který používá komunita kolem programu [[http://eigen.tuxfamily.org/index.php?title=Main_Page|Eigen]], z jejichž webových stránek následující stručný tutoriál pochází. ''' ''' <<TableOfContents(3)>> == Instalace Mercurialu a přístup k dokumentaci == * Používáte-li Windows nebo Mac, stáhněte si Mercurial z [[http://hg-scm.org/downloads/|tohoto webu]]. * Používáte-li Unix/Linux, instalujte si Mercurial ze správce programů. Chcete-li používat grafické rozhraní, nainstalujte si TortoiseHg. Následující popisy se nicméně budou vztahovat pouze na rozhraní příkazového řádku. V předkládaném návodu naleznete jenom některé běžně užívané příkazy. Bližší informace lze vyhledat v hojné dokumentaci, přístupné na těchto stránkách: * [[CzechUnderstandingMercurial|Základní pojmy Mercurialu]] * [[CzechTutorial|Tutoriál Mercurialu]] * [[http://hginit.com|Joel Spolsky: Hg Init]] == Základní použití == === Získání zdrojového textu === Počáteční převzetí (checkout) repozitáře: {{{ $ hg clone https://bitbucket.org/eigen/eigen }}} případně přes protokol SSH: {{{ $ hg clone ssh://hg@bitbucket.org/eigen/eigen/ }}} (viz návod pro nastavení ssh na: http://bitbucket.org/help/using-ssh/) Poté svůj klonovaný repozitář můžete aktualizovat (to jest získat nové změny zdrojového repozitáře) příkazem: {{{ $ hg pull -u # příkaz hg pull přenese změny do vaší složky .hg/store a opce -u # způsobí aktualizaci vašeho pracovního adresáře. # 'hg pull -u' je totéž jako 'hg pull && hg update'. }}} === Konfigurace Mercurialu === Před použitím Mercurialu je zapotřebí provést konfiguraci nainstalovaného programu a to editací jeho konfiguračního souboru (popřípadě jeho vytvoření). *Na Unixových systémech je globálním konfiguračním souborem soubor ~/.hgrc, který musíte ve svém repozitáři vytvořit (např. eigen/.hgrc). *Na systémech Windows je globálním konfiguračním souborem soubor %HOME%/Mercurial.ini, který se vytvoří při instalaci programu. Potřebujete-li pro každý projekt jiný konfigurační soubor, použijete lokální konfigurační soubor .hg/hgrc, který jste převzal při klonování. Doporučujeme používat přednostně globální konfigurační soubor. Do konfiguračního souboru vložte tyto řádky: {{{ [diff] git = 1 showfunc = 1 unified = 8 [defaults] commit = -v [ui] username = Your Real Name <your.email@address.com> merge = internal:merge editor = YourFavoriteEditorExecutable }}} Ve výše uvedeném příkladu konfiguračního souboru nahradíte některé obecné výrazy konkretními hodnotami: * Vložíte své '''skutecne jmeno''' a '''skutecnou emailovou adresu'''. * Zadáte svůj oblíbený editor. Bude používán k psaní komitových zpráv. === Poznámka pro uživatele Windows === Při problému s kódováním konce řádku (EOL), můžete nahlédnout do pokynů [[http://mercurial.selenic.com/wiki/Win32TextExtension|pro extenzxi Win32Text]]. Načež patrně přidáte tyto řádky do svého konfiguračního souboru: {{{ [extensions] hgext.win32text= [encode] ** = cleverencode: [decode] ** = cleverdecode: [patch] eol = crlf [hooks] pretxncommit.crlf = python:hgext.win32text.forbidcrlf }}} === Větve (branches) === Implicitně pracujeme s vývojovou větví, zvanou 'default branch.' {{{ $ hg branch # zobrazit jméno aktuální větve $ hg branches # zobrazit seznam větví $ hg up 2.0 # přejít do větve 2.0 }}} === Lokální komit (commit) === Nejprve se ujistěte, že jsou všechny nové soubory postoupeny správě revizí: {{{ $ hg add <filename> # postoupit soubor správě revizí }}} Potom se ještě před komitem můžete ujistit: {{{ $ hg status # zjistit, kterých souborů se bude komit týkat $ hg diff # ukázat rozdíly u komitovaných souborů }}} Nyní můžete přistoupit k provedení vlastního komitu: {{{ $ hg commit # provede registraci změn (commit) v celém repozitáři i když se třeba aktuálně nacházíte v subrepozitáři $ hg commit . # chcete-li komitovat změny jenom lokálního adresáře }}} Otevře se váš vybraný textový editor a bude použita vaše zadaná identita. === Zrušení nekomitovaných změn === Nekomitované změny můžete odvolat (zrušit) příkazy: {{{ $ hg revert <soubor> # zruší nekomitované změny souboru $ hg revert -a # zruší nekomitované změny všech souborů. Opatrně! }}} === Zrušení lokálního komitu === '''Poznámka''': Lokální komit je dosud nepublikovaná (např. příkazem hg push) transakce, provedená v lokálním repozitáři. Globální komit neexistuje. Posledně provedený komit lze odvolat (zrušit) příkazem: {{{ $ hg rollback # vycouvat z poslední transakce }}} === Vytvoření oprávky (patch) === Z komitovaných změn můžete vygenerovat oprávkový soubor (patch): {{{ $ hg export tip > somefile }}} Označením 'tip' je míněna poslední revize. Další možnosti zjistíte přikazem "hg help export". Příkaz hg export vygeneruje soubor, který lze přiložit k hlášení o chybě. Máte-li správně nastavenou svou identitu, nebude import vaší oprávky (patch) působit žádné nesnáze. === Odesílání lokálních změn do centrálního repozitáře === Komitované změny můžete odeslat do centrálního repozitáře. {{{ $ hg out # ukázat, co se posílá $ hg push # odeslat komity do zdroje klonovaného repozitáře }}} Můžete se setkat s touto chybovou zprávou: {{{ abort: push creates new remote heads! (did you forget to merge? use push -f to force) ruší se: push vytváří nová vzdálená čela (heads)! zapomněl jste provést sloučení (merge)? použijte push -f trváte-li na odeslání a víte-li, co činíte }}} Příjmu takové zprávy se vyhnete důsledným dodržováním zásady, že před každým odesláním (push) si sám stáhnete (pull) aktuální změny z centrálního repozitáře a v případě potřeby provedete sloučení stažených změn se změnami vašeho lokálního repozitáře. === Sloučení změn ze vzdáleného repozitáře === {{{ $ hg in <repo> # podívat se, co bude stahováno $ hg pull <repo> # stáhnout changesety ze vzdáleného <repa> $ hg merge # začlenit nový tip ze vzdáleného <repa> do vašeho pracovního adresáře $ hg parents # zobrazit sloučené revize $ hg commit # komitovat výsledek sloučení }}} After 'hg merge', you may see this error message: {{{ warning: conflicts during merge. merging <filename> failed! 0 files updated, 0 files merged, 0 files removed, x files unresolved }}} In that case, read the section "Resolving Conflicts" below. === Resolving conflicts === This is very similar to SVN. After a 'hg merge' has found conflicts, the files are left with special markers at the locations of conflicts, like: {{{ <<<<<<< local Hello Sir ======= Hello Madam >>>>>>> other }}} You have to edit these files manually to resolve the conflict. Once a file <filename> is fixed, do: {{{ hg resolve -m <filename> # mark the file as resolved }}} Once all the files are marked as resolved, you can proceed with committing. === Viewing history === The basic command here is 'hg log'. If you want to see full information about a certain revision, you can do: {{{ $ hg log --style changelog -r 1000 # examine revision 1000 $ hg log -u someuser # see all commits made by someuser }}} But you can also enable a couple of extensions that provide fancier views. Edit (or create) your global .hgrc file (in your home directory) and add these lines: {{{ [extensions] hgk= hgext.graphlog = }}} You can now enjoy a graphical view of the commit history: {{{ $ hgk # or try 'hg view' if that doesn't work }}} Or if you prefer a plain text output of the graph: {{{ $ hg glog }}} Finally, if you want something more powerful, have a look at the following external programs: hgtk and hgview. [[http://bitbucket.org/tortoisehg/stable/wiki/hgtk|Hgtk]] allows many things, like viewing only as specific branch, viewing only merges, etc. Do: {{{ $ hgtk log }}} [[http://www.logilab.org/project/name/hgview|Hgview]] is simpler but still allows viewing a specific branch: {{{ $ hgview }}} == Advanced usage == === Porting a changeset to another branch === First of all, you should a separate local clone for each of the branches that you're interested in. If you want to transplant a changeset, say, from the default branch to the 2.0 branch, enter your clone of the 2.0 branch, make sure that you have pulled the changeset that you want to transplant, and do: $ hg export REV | hg import - There also is a [http://www.selenic.com/mercurial/wiki/TransplantExtension|transplant extension]. === Mercurial Queues === If you're feeling dangerous today, read about [[Mercurial Queues]]. This makes Mercurial about as dangerous as [http://git-scm.org|Git]. === Pushing many local commits as a single one === If you want to do this, you want Mercurial Queues, see above. Specifically, the qfold command. If you're not very comfortable with Mercurial, don't bother. === Splitting a patch into smaller patches === The best way to do that is using the [http://mercurial.selenic.com/wiki/CrecordExtension Crecord extension]. It has an interactive interface to let you select line-by-line or hunk-by-hunk how to split your patch. This extension also provides a 'hg qcrecord' command to interoperation with [[Mercurial Queues]], making it even more powerful. We explain it [[Mercurial_Queues#Splitting_a_patch.2C_the_general_case.2C_including_per-hunk_and_per-line_splitting|there]]. === Rebasing changesets === '''Warning''': rebasing is not something trivial, and can break a repository. Typically, if you push changes, then do some rebasing, this is a '''very bad''' thing. The remote repository might get corrupted. The most obvious way is to use 'hg rebase', or 'hg update --rebase'. See respective documentation. If you are such a power user that you know how to use Mercurial Queus (MQ, see above), this is another way to do almost automatic rebasing. Once your changeset is a MQ patch, you can pop it, update your hg repository to another changeset, and push it again. == Receiving commit notification == The Bitbucket web interface offers RSS and Atom feeds. If you prefer email notification, subscribe to the eigen-commits mailing list. Instructions are the same as for the [[Main_Page#Mailing_list|eigen mailing list]], just replace "eigen" by "eigen-commits" everywhere. == Search and replace on whole directory == If you do a search-and-replace operation on a whole directory, you probably do not want it to affect Mercurial's own internal files! So you must avoid all .hg directories. You can do: $ find . -type f | grep -v \\.hg | xargs sed -i 's/oldstring/newstring/g' == Make a new release == These days it's very easy, as the docs are automatically generated and uploaded by Thomas' machine, and the tarballs are auto-generated by Bitbucket. So here's what it takes to make a new release (a new minor version): * Announce a week in advance on the [[Main_Page#Mailing_list|eigen mailing list]] the upcoming release (give a precise date) so that people can test and/or speak up if they know of an issue. Of course, in case of an emergency, no need to do that :) * Concert with other devs, and/or use CDash, and/or test yourself, to make sure that the test suite passes at the very least for: * latest stable GCC * some older GCC 4.x (ok, it's hard to check them all), try to cover the oldest GCC we're supposed to support (see main page) * latest MSVC * latest Clang * Also do think to check "make install"! Remember how it spoiled the 2.0.7 release! * Supreme refinement would be to check building the test suite against the installed Eigen. * Update the version number (EIGEN_MINOR_VERSION, etc) in the file Eigen/src/Core/util/Macros.h. * In the 2.0 branch, also update the version number in the root CMakeLists.txt. That doesn't apply to the default branch. * commit that: $ hg commit * Make a tag: $ hg tag 4.5.6-beta7 * recommended: check that everything is in order. $ hg view * push the release: $ hg push * For a minor version: make the full changelog. It's not just a dump of the commit messages: it must be readable and interesting for Eigen users. You can use "hg view" again, try to put the grave bug fixes first, try to group together what's related. * Update the [[Main_Page|Main Page]] on the wiki, that is the announcement at the top and the [[Main_Page#Download|Download]] section. Make sure that the tarball links point to the new release, and that any example of how to get the latest tag also refers to the new tag. * To add a news, simply create a new page in the "News" namespace: 1. enter "News:Title of my great announcement!" in the search box, 1. press search, and click "create a new page", 1. write your news as usual, preview, save... 1. you might have to enforce the regeneration of the mainpage by editing/saving it (because of mediawiki's cache) * Add the release notes into the [[ChangeLog]] page. * Write a mail to the [[Main_Page#Mailing_list|eigen mailing list]], paste the changelog into it. * Update the #eigen channel topic on IRC. |
