| 5 | | |
| 6 | | |
| 7 | | = Common scenario = |
| 8 | | |
| 9 | | Those scenario are the basics - they are written to minimize as much as possible disruption from the common svn workflows. They are not necessarily the best ways to do a specific task under git, but they are the least surprising for someone used to git. |
| 10 | | |
| 11 | | == Scenario 0: setting up git == |
| 12 | | |
| 13 | | === Installation === |
| 14 | | |
| 15 | | Please do not use any version of git below 1.5.3. |
| 16 | | |
| 17 | | ==== Linux ==== |
| 18 | | |
| 19 | | Git is included in most linux distributions (git-core on Ubuntu). |
| 20 | | |
| 21 | | ==== Mac OS X ==== |
| 22 | | |
| 23 | | Reasonably up to date binary installers can be found here: http://code.google.com/p/git-osx-installer/. |
| 24 | | |
| 25 | | Installing git itself from sources is easy, but installing the documentation (man, html and info) is a PITA, with many dependencies (asciidoc, etc...). So avoid it if you don't want to go through the hassle. |
| 26 | | |
| 27 | | ==== Windows ==== |
| 28 | | |
| 29 | | There are two easy ways to install git: the native installer or the cygwin installer. Unless you are a regular user of cygwin, the native installer is the best choice. It can be found there: http://code.google.com/p/msysgit/ |
| 30 | | |
| 31 | | === GUI === |
| 32 | | |
| 33 | | Git has a basic TK-based GUI, called gitk. It works well to navigate the history. There are native UI for git for most platforms, including windows and mac os X: |
| 34 | | |
| 35 | | * TortoiseGit: http://code.google.com/p/tortoisegit/ |
| 36 | | * gitx (native mac os X client): http://gitx.frim.nl |
| 37 | | |
| 38 | | === basic configuration === |
| 39 | | |
| 40 | | At minimum, set up your name and email, so that they appear correctly for commits: |
| 41 | | |
| 42 | | {{{ |
| 43 | | git config --global user.name "Your Name Comes Here" |
| 44 | | git config --global user.email name@domain.example.com |
| 45 | | }}} |
| 46 | | |
| 47 | | You can add some aliases so that some git commands spell like the svn ones. The following are useful: |
| 48 | | |
| 49 | | {{{ |
| 50 | | git config alias.co checkout |
| 51 | | git config alias.ci commit |
| 52 | | git config alias.st status |
| 53 | | }}} |
| 54 | | |
| 55 | | === Getting help from the command line === |
| 56 | | |
| 57 | | Git documentation is pretty massive - it can definitely be difficult to apprehend. Once you have a good grasp of the basic scenario, you should familiarize yourself with git from the git tutorial, and git for svn users. Only then will you be able to start reading the git included help. |
| 58 | | |
| 59 | | == Scenario 1: getting the numpy source code == |
| 60 | | |
| 61 | | Getting the sources from the NumPy repository, just to look at the sources, or to build from last version instead of released: |
| 62 | | |
| 63 | | {{{ |
| 64 | | git clone http://git.scipy.org/git/numpy numpy |
| 65 | | }}} |
| 66 | | |
| 67 | | Do NOT use checkout - checkout has a different meaning than in svn. Clone is what you want. |
| 68 | | |
| 69 | | A tarball will also be made available on the scipy website, so that you don't need git at all in this scenario. |
| 70 | | |
| 71 | | == Scenario 2: prepare a simple patch ala svn, don't bother me with git == |
| 72 | | |
| 73 | | I have found a bug, and I want to submit a patch. I want to do it like in svn, I don't care about git: |
| 74 | | |
| 75 | | {{{ |
| 76 | | # This will list the changed files |
| 77 | | git status |
| 78 | | # This will put the changes into a patch |
| 79 | | git diff |
| 80 | | }}} |
| 81 | | |
| 82 | | Maybe: we could have a svn mirror of git ? |
| 83 | | |
| 84 | | == Scenario 3: reverting changes == |
| 85 | | |
| 86 | | I have made some changes, but I am confused, I just want to restart from last revision and throw everything away. |
| 87 | | |
| 88 | | There are several solutions - do NOT use revert, git revert is totally different from svn revert. The safe and easy one: |
| 89 | | |
| 90 | | {{{ |
| 91 | | git stash |
| 92 | | }}} |
| 93 | | |
| 94 | | This will put your changes aside (in a 'stash'), and your working tree will be exactly as if you checked out from the last revision of your repository. It is safe because your changes are not lost - you can reapply them: |
| 95 | | |
| 96 | | {{{ |
| 97 | | git stash apply |
| 98 | | }}} |
| 99 | | |
| 100 | | If you really don't care about the changes, and are ready to throw them away with no change of recovering: use the checkout option: |
| 101 | | |
| 102 | | {{{ |
| 103 | | git co myfile |
| 104 | | }}} |
| 105 | | |
| 106 | | This will have the same semantics as svn revert. |
| 107 | | |
| 108 | | Q: I thought that git reset was the option to use ? |
| 109 | | |
| 110 | | No, don't use git reset. Git reset can be used to revert changes, but can be dangerous to use, as it can also remove *commits*, not just changes. git reset is only useful for advanced usage of git. Use git stash or git co, not git reset. |
| 111 | | |
| 112 | | == Scenario 4: simple commits, no branching == |
| 113 | | |
| 114 | | To do a commit, use the commit option: |
| 115 | | |
| 116 | | {{{ |
| 117 | | git commit -am "My commit." |
| 118 | | }}} |
| 119 | | |
| 120 | | The -m option has the same meaning as the svn commit command. By default (without the "-a"), git only commits the changes you explicitly told him about with the add command (TODO: ref to git-specific workflows). Although extremely useful, it can be a bit confusing at first when you come from a svn background, hence the -a option. |
| 121 | | |
| 122 | | A big difference of git compared to svn which cannot be skipped even at this level: git clone gives you a working tree (a snapshot of the sources at one revision) AND the repository with the full history. It means in particular that committing a change will NOT propagate it to the original repository you cloned from. For this, you need to use push: |
| 123 | | |
| 124 | | {{{ |
| 125 | | git push git.scipy.org/git/numpy |
| 126 | | }}} |
| 127 | | |
| 128 | | TODO: handling of remote locations. |
| 129 | | |
| 130 | | = A first few git specific workflows = |
| 131 | | |
| 132 | | Before showing a few simple but powerful git-specific workflows, we need to talk about two features of git. One, branches, is not specific to git, but the index concept is, and a basic understanding is necessary for most git-specific workflows. |
| 133 | | |
| 134 | | == The branch concept == |
| 135 | | |
| 136 | | Git, like other DVCS, is strongly designed around the notion of branches. Instead of everyone committing directly to the trunk, most development happen in branches, which are then merged into the trunk. What's the point, you may ask ? |
| 137 | | |
| 138 | | * commit is fast: it is instantaneous. |
| 139 | | * branches are isolated: if you work on a non trivial feature, having a separate branch means you can commit regularly on it, without pushing things into the "trunk". In particular, you can break things without disturbing anyone else. |
| 140 | | * branches are a useful unit of decomposition. Although it still certainly makes sense to commit things directly into the main line of development, regularly using separate branches is a good way to split tasks. This is especially useful for reviews: having a separate branch means everyone can easily look at those changes only. The examples will obviously make this clearer. |
| 141 | | |
| 142 | | == The index and content-oriented tracking == |
| 143 | | |
| 144 | | In the simple scenarios, we mentioned the '-a' option as necessary to commit all changes. That's because in git, you have to explicitly say which changes you want in a commit. Although a minor inconvenience in simple cases, this is extremely useful in advanced cases, especially for complex merges (to deal with conflict). This is linked to the fundamental idea that git tracks content, and not files. When you do |
| 145 | | |
| 146 | | {{{ |
| 147 | | git add foo.c |
| 148 | | }}} |
| 149 | | |
| 150 | | You are not really adding the file foo.c to the repository, but you add its content to the git repository. |
| 151 | | |
| 152 | | == Scenario 1: creating a new branch == |
| 153 | | |
| 154 | | Creating a new branch to make my changes. |
| 155 | | |
| 156 | | {{{ |
| 157 | | # Create a branch from an old branch named oldbranch |
| 158 | | git branch newbranch oldbranch |
| 159 | | # Switch to the new branch |
| 160 | | git checkout newbranch |
| 161 | | }}} |
| 162 | | |
| 163 | | This can be done in one command: |
| 164 | | |
| 165 | | {{{ |
| 166 | | git co -b newbranch oldbranch |
| 167 | | }}} |
| 168 | | |
| 169 | | Now, every commit will be put in newbranch. Again, as for commits, the branch is only created in your repository, and not propagated to the remote repository, unless you explicitly push for it: |
| 170 | | |
| 171 | | {{{ |
| 172 | | # This push all the changes in newbranch onto the remote repository |
| 173 | | git push url_repo newbranch |
| 174 | | }}} |
| 175 | | |
| 176 | | == Scenario 2: comparing branches == |
| 177 | | |
| 178 | | This is one example where git is much more powerful AND easier than svn :) To compare HEAD of two branches (that is the last revision of each branch), you simply use the branch1..branch2 syntax: |
| 179 | | |
| 180 | | {{{ |
| 181 | | # Get the diff "between" two branches |
| 182 | | git diff oldbranch newbranch |
| 183 | | # Get the log of commits "between" two branches |
| 184 | | git log oldbranch newbranch |
| 185 | | }}} |
| 186 | | |
| 187 | | We use "between" very loosely. For the simple following scenario: |
| 188 | | |
| 189 | | |
| 190 | | - o -- o -- o oldbranch |
| 191 | | \ -- o -- o newbranch |
| 192 | | |
| 193 | | Where o is one commit, the above commands will give you the commits specific to newbranch AND the commits from oldbranch since newbranch was started. To get only the changes related to the commit *specific* to new branch, use the ... syntax instead: |
| 194 | | |
| 195 | | {{{ |
| 196 | | git diff oldbranch...newbranch |
| 197 | | git log oldbranch...newbranch |
| 198 | | }}} |
| 199 | | |
| 200 | | Note the difference between '..' and '...'. '..' (2 dots) is the same as a space. |
| 201 | | |
| 202 | | == Scenario 3: Merging branches == |
| 203 | | |
| 204 | | Merging branches is easy: |
| 205 | | |
| 206 | | {{{ |
| 207 | | # Will merge branch1 into the current branch |
| 208 | | git merge branch1 |
| 209 | | }}} |
