en/clone.txt

   1 == Cloning Around ==
   2
   3 In older version control systems, checkout is the standard operation to get files. You retrieve a bunch of files in the requested saved state.
   4
   5 In Git and other distributed version control systems, cloning is the standard operation. To get files you create a clone of the entire repository. In other words, you practically mirror the central server. Anything the main repository can do, you can do.
   6
   7 === Sync Computers ===
   8
   9 This is the reason I first used Git. I can tolerate making tarballs or using *rsync* for backups and basic syncing. But sometimes I edit on my laptop, other times on my desktop, and the two may not have talked to each other in between.
  10
  11 Initialize a Git repository and commit your files on one machine. Then on the other:
  12
  13  $ git clone other.computer:/path/to/files
  14
  15 to create a second copy of the files and Git repository. From now on,
  16
  17  $ git commit -a
  18  $ git pull other.computer:/path/to/files HEAD
  19
  20 will pull in the state of the files on the other computer into the one you're working on. If you've recently made conflicting edits in the same file, Git will let you know and you should commit again after resolving them.
  21
  22 === Classic Source Control ===
  23
  24 Initialize a Git repository for your files:
  25
  26  $ git init
  27  $ git add .
  28  $ git commit -m "Initial commit"
  29
  30 On the central server, initialize an empty Git repository with some name,
  31 and start the Git daemon if necessary:
  32
  33  $ GIT_DIR=proj.git git init
  34  $ git daemon --detach  # it might already be running
  35
  36 For Git hosting services, follow the instructions to setup the initially
  37 empty Git repository. Typically one fills in a form on a webpage.
  38
  39 Push your project to the central server with:
  40
  41  $ git push git://central.server/path/to/proj.git HEAD
  42
  43 The central server now holds a 'bare repository': a repository with no working directory. In other words, the central server has the history of your project, but never contains a snapshot of it. To check out source, a developer types:
  44
  45  $ git clone git://central.server/path/to/proj.git
  46
  47 After making changes, the code is checked in to the main server by:
  48
  49  $ git commit -a
  50  $ git push
  51
  52 If the main server has been updated, the latest version needs to be checked out before the push. To sync to the latest version:
  53
  54  $ git commit -a
  55  $ git pull
  56
  57 === Push versus pull ===
  58
  59 A push is more convenient than a pull in the above example. If we pulled from the server, we would have to login to the server first, and give the pull command the network address of the machine we're pulling from. Firewalls may interfere, and we might not even have shell access to the server.
  60
  61 However, we usually avoid pushing into a repository, because confusion can ensue if the destination has a working directory with changes. But since a bare repository by definition has no working directory, pushing to a bare repository is a straightforward operation.
  62
  63 In short, while learning Git, only push when the target is a bare repository; otherwise pull.
  64
  65 === Forking a Project ===
  66
  67 Sick of the way a project is being run? Think you could do a better job? Then on your server:
  68
  69  $ git clone git://main.server/path/to/files
  70
  71 Next tell everyone about your fork of the project at your server.
  72
  73 At any later time, you can merge in the changes from the original project with:
  74
  75  $ git pull
  76
  77 === Ultimate Backups ===
  78
  79 Want numerous tamper-proof geographically diverse redundant archives? If your project has many developers, don't do anything! Every clone of your code is effectively a backup. Not just of the current state, but of your project's entire history. Thanks to cryptographic hashing, if anyone's clone becomes corrupted, it will be spotted as soon as they try to communicate with others.
  80
  81 If your project is not so popular, find as many servers as you can to host clones.
  82
  83 The truly paranoid should always write down the latest 20-byte SHA1 hash of the HEAD somewhere safe. It has to be safe, not private. For example, publishing it in a newspaper would work well, because it's hard for an attacker to alter every copy of a newspaper.
  84
  85 === Light-Speed Multitask ===
  86
  87 Say you want to work on several features in parallel. Then commit your project and run:
  88
  89  $ git clone . /some/new/directory
  90
  91 Git exploits hard links and file sharing as much as safely possible to create this clone, so it will be ready in a flash, and you can now work on two independent features simultaneously. For example, you can edit one clone while the other is compiling.
  92
  93 At any time, you can commit and pull changes from the other clone.
  94
  95  $ git pull /the/other/clone HEAD
  96
  97 === Guerilla Version Control ===
  98
  99 Are you working on a project that uses some other version control system, and you sorely miss Git? Then initialize a Git repository in your working directory:
 100
 101  $ git init
 102  $ git add .
 103  $ git commit -m "Initial commit"
 104
 105 then clone it:
 106
 107  $ git clone . /some/new/directory
 108
 109 Now go to the new directory and work here instead, using Git to your heart's content. Once in a while, you'll want to sync with everyone else, in which case go to the original directory, sync using the other version control system, and type:
 110
 111  $ git add .
 112  $ git commit -m "Sync with everyone else"
 113
 114 Then go to the new directory and run:
 115
 116  $ git commit -a -m "Description of my changes"
 117  $ git pull
 118
 119 The procedure for giving your changes to everyone else depends on the other version control system. The new directory contains the files with your changes. Run whatever commands of the other version control system are needed to upload them to the central repository.
 120
 121 Subversion, perhaps the best centralized version control system, is used by countless projects. The *git svn* command automates the above for Subversion repositories, and can also be used to http://google-opensource.blogspot.com/2008/05/export-git-project-to-google-code.html[export a Git project to a Subversion repository].
 122
 123 === Mercurial ===
 124
 125 Mercurial is a similar version control system that can almost seamlessly work in tandem with Git. With the `hg-git` plugin, a Mercurial user can losslessly push to and pull from a Git repository.
 126
 127 Obtain the `hg-git` plugin with Git:
 128
 129  $ git clone git://github.com/schacon/hg-git.git
 130
 131 or Mercurial:
 132
 133  $ hg clone http://bitbucket.org/durin42/hg-git/
 134
 135 Sadly, I am unaware of an analogous plugin for Git. For this reason, I advocate Git over Mercurial for the main repository, even if you prefer Mercurial. With a Mercurial project, usually a volunteer maintains a parallel Git repository to accommodate Git users, whereas thanks to the `hg-git` plugin, a Git project automatically accommodates Mercurial users.
 136
 137 Although the plugin can convert a Mercurial repository to a Git repository by pushing to an empty repository, this job is easier with the `hg-fast-export.sh` script, available from:
 138
 139  $ git clone git://repo.or.cz/fast-export.git
 140
 141 To convert, in an empty directory:
 142
 143  $ git init
 144  $ hg-fast-export.sh -r /hg/repo
 145
 146 after adding the script to your `$PATH`.
 147
 148 === Bazaar ===
 149
 150 We briefly mention Bazaar because it is the most popular free distributed
 151 version control system after Git and Mercurial.
 152
 153 Bazaar has the advantage of hindsight, as it is relatively young; its designers could learn from mistakes of the past, and sidestep minor historical warts. Additionally, its developers are mindful of portability and interoperation with other version control systems.
 154
 155 A `bzr-git` plugin lets Bazaar users work with Git repositories to some extent. The `tailor` program converts Bazaar repositories to Git repositories, and can do so incrementally, while `bzr-fast-export` is well-suited for one-shot conversions.
 156
 157 === Why I use Git ===
 158
 159 I originally chose Git because I heard it could manage the unimaginably unmanageable Linux kernel source. I've never felt a need to switch. Git has served admirably, and I've yet to be bitten by its flaws. As I primarily use Linux, issues on other platforms are of no concern.
 160
 161 Also, I prefer C programs and bash scripts to executables such as Python scripts: there are fewer dependencies, and I'm addicted to fast running times.
 162
 163 I did think about how Git could be improved, going so far as to write my own Git-like tool, but only as an academic exercise. Had I completed my project, I would have stayed with Git anyway, as the gains are too slight to justify using an oddball system.
 164
 165 Naturally, your needs and wants likely differ, and you may be better off with another system. Nonetheless, you can't go far wrong with Git.