Changes between Initial Version and Version 1 of DVCS


Ignore:
Timestamp:
Sep 15, 2017, 10:50:46 AM (7 years ago)
Author:
Olivier Mattelaer
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • DVCS

    v1 v1  
     1= The Bazaar Distributed Version Control System (DVCS) =
     2
     3== Install Bazaar ==
     4
     5This is the only version control system we are using. The stable version is available for all platforms on http://bazaar-vcs.org/Download. Use the latest version 1.X available for your platform. We’ll switch to 2.X later. There are no big differences anyway, but everybody has to have version 2.X to move to the new repository format, and binaries are not yet distributed for all platforms.
     6
     7Tell Bazaar who you are by typing
     8
     9{{{
     10bzr whoami "John Doe <john.doe@gmail.com>"
     11}}}
     12
     13in a command line.
     14
     15== Learn Bazaar ==
     16
     17Ideally, everybody should read http://doc.bazaar-vcs.org/bzr.dev/en/user-guide/index.html (or at least use it as a reference).
     18
     19Alternatively, a minimal tutorial can be found here: http://doc.bazaar-vcs.org/bzr.dev/en/mini-tutorial/index.html
     20
     21For reference: http://doc.bazaar-vcs.org/bzr.dev/en/user-reference/bzr_man.html
     22
     23A very useful small PDF reference card to leave on your desk: http://doc.bazaar-vcs.org/bzr.dev/_static/en/quick-reference/bzr-quick-reference.pdf
     24
     25== Mini How-to, Bazaar in a command line ==
     26
     27WARNING: even if you use Eclipse, learning a minimum of Bazaar in the command line is VERY important (some command are not available from Eclipse, and the Bazaar plugin is not always very stable)
     28
     29To use Bazaar you need to understand four core concepts:
     30
     31 * Revision - a snapshot of the files you're working with. Each revision has a unique revision number. All files have the same revision number.
     32 * Working tree - the directory containing your version-controlled files and sub-directories.
     33 * Branch - an ordered set of revisions that describe the history of a set of files.
     34 * Repository - a store of revisions.
     35
     36First, create a new local repository (set of branches) and create a mirror branch inside (a pristine copy of the central branch):
     37
     38{{{
     39bzr init-repo MADGRAPH --format=1.14
     40
     41cd MADGRAPH
     42
     43bzr branch lp:madgraph5/trunk
     44}}}
     45
     46We use the 1.14 format which is the "old" bazaar format everybody can use, whatever his/her version of bazaar. This can be changed in the future.
     47
     48Now, create a local task branch (a linked copy of the mirror branch, where you actually work)
     49
     50{{{
     51bzr branch trunk fix-123
     52
     53cd fix-123
     54}}}
     55
     56In principle, it’s not forbidden to work directly in the mirror branch, but this should be avoided for important modifications.
     57
     58Here is a typical development cycle inside fix-123 (only local, and as many as you want!):
     59
     60{{{
     61(hack some files)
     62
     63bzr commit
     64
     65(hack some files, you can add new ones with bzr add)
     66
     67bzr status (to see a summary of what has been done since last commit)
     68
     69bzr diff (to see what has been actually changed)
     70
     71bzr log (to see the history of the branch)
     72
     73bzr commit
     74
     75...
     76}}}
     77
     78Sometimes, you might want to refresh the mirror branch:
     79
     80{{{
     81cd ../trunk
     82
     83bzr pull
     84}}}
     85
     86And you might also want to merge the latest trunk into the task branch
     87
     88{{{
     89cd fix-123
     90
     91bzr merge ../trunk
     92
     93(resolve conflicts)
     94
     95bzr commit -m “merged trunk”
     96}}}
     97
     98At some point, you might want to distribute your local task branch to collaborate with other people. Try
     99
     100{{{
     101bzr push lp:~madteam/madgraph5/mybranch
     102}}}
     103
     104from your local branch directory (you can also use your local directory with ~myname instead of ~madteam). Then, all instructions above apply for people starting from mybranch instead of trunk (that’s the real magic of distributed VCS)! Note that this branch will belong to the “madteam”. You can also replace “madteam” by your Launchpad login to create a personal branch. There are also project branches (same level as trunk), but those should be reserved for long term parallel development (a.k.a. “series” in the Launchpad jargon), and their creation should be approved by the whole team.
     105
     106Finally, once you think your branch can be merged to the main trunk (you need to have write access to the trunk):
     107
     108{{{
     109cd trunk
     110
     111bzr pull
     112
     113bzr merge ../fix-123
     114
     115(resolve conflicts)
     116
     117bzr commit -m “Fixed bug #123”
     118
     119RUN TESTS
     120
     121bzr push
     122}}}
     123
     124== More evolved things with Bazaar ==
     125
     126=== Resolve ===
     127
     128The “resolve conflicts” step is particularly sensible, but things are rather simple with bazaar. If it finds possible conflicts in file foo (i.e. there is a modification in the trunk incompatible with a modification in the task branch), it will create automatically four files:
     129
     130 * foo: your file with merge markers
     131 * foo.BASE: the state the file was in when you started working on it
     132 * foo.THIS: your changes to the file
     133 * foo.OTHER: the changes done to the file while you were working on it
     134you can diff all those files (e.g. using the compare tool in Eclipse) to understand what’s going on, and then simply edit the file foo, choose the changes that you want and remove the merge markers. Then you have to tell bazaar you are done by typing
     135
     136{{{
     137bzr resolve foo
     138}}}
     139
     140Bazaar will detect your fix and remove the BASE/THIS/OTHER files.
     141
     142=== Send ===
     143
     144If an EXTERNAL user work on a local private branch (using exactly the same tool as us), at the very end, he/she (of course) cannot do a push to the trunk. Instead, he would do
     145
     146{{{
     147bzr send -o ../fix-123.patch
     148}}}
     149
     150This patch can be sent to us by email, used later as a branch (e.g. bzr merge fix-123.patch) and is compatible with the standard linux patch format.
     151
     152=== Undoing mistakes ===
     153
     154Undoing changes since the last commit (everything will be lost!):
     155
     156{{{
     157bzr status
     158
     159bzr revert (name_of_a_file)
     160}}}
     161
     162You can specify an older revision number with “-r 19” (go back to revision 19), or even “-r -2” (go back two revisions)
     163
     164Undoing last commit:
     165
     166{{{
     167bzr uncommit
     168}}}
     169
     170=== Removing a file/dir ===
     171
     172{{{
     173bzr remove foo (--keep if you just want to remove versionning info)
     174}}}
     175
     176If a file is removed from the disk, commit will considered it as removed anyway
     177
     178=== Export ===
     179
     180Sometimes, you might want to export your branch as a tar.gz (for official releases, communication with external beta testers, ...)
     181
     182{{{
     183bzr commit
     184
     185bzr tag version-1.5 (not necessary but useful to come back to that version later with -r tag:version-1.5)
     186
     187bzr export ../madgraph-1.5.tar.gz
     188}}}
     189
     190Bazaar will take care of everything for you (remove versioning info, creating the tar.gz, ...)
     191
     192=== Working centralized (with checkout, bind, update, ...) ===
     193
     194NO WAY!!!! we do not encourage (at first) this way of working, even if Bazaar supports it. So forget about those commands.