1 Git Basics
2 ==========
3 :author: Aaron Ball
4 :email: nullspoon@iohq.net
5
6
7 == {doctitle}
8
9 Git can be a very complicated thing. Someone once told me that we mere humans
10 have a very difficult time with it at first. I myself have had a
11 tremendous<nowiki>[ly difficult]</nowiki> time learning how to use Git (many
12 thanks to http://marktraceur.info/[marktraceur] for all the help). It is an
13 incredibly robust and so a very complicated solution. What source code
14 management system isn't though (especially one that is command line)? This
15 document should serve as a very high level view of how to use Git. It will not
16 cover advanced functionality such as
17 http://git-scm.com/docs/git-cherry-pick[cherry-picking],
18 http://git-scm.com/docs/git-merge[merging],
19 http://git-scm.com/docs/git-rebase[rebasing], etc. If something is not
20 documented here, please see the http://git-scm.com/docs[Git docs] or suggest it
21 on the discussion page.
22
23 [[working-with-branches]]
24 Working with Branches
25 ---------------------
26
27 Branches in Git look are like tree branches. The Git repository itself is the
28 trunk and the branches are the various projects in the repository. Typically
29 (hopefully) these projects are related to each other. In the case of a
30 development project with a frequently changing database schema that you wanted
31 to back up, the repository would have two branches: the files branch where the
32 code files are stored, and the database branch where the database dumps are
33 stored.
34
35 [[viewing-branches]]
36 Viewing Branches
37 ~~~~~~~~~~~~~~~~
38
39 Viewing branches is simple. Type *git branch* and you should see output
40 similar to the following:
41
42 ----
43 $ git branch
44
45 * database
46 master
47 ----
48
49 To use a different branch, a the checkout command is required. In this case, we
50 will switch from the _database_ branch to the _master_ branch.
51
52 Note:Some decompression happens here so if the branch to be checked out is very
53 large, this will likely take a few seconds.
54
55 ----
56 $ git checkout master
57
58 Checking out files: 100% (6110/6110), done.
59 Switched to branch 'master'
60 ----
61
62 [[commits]]
63 Commits
64 -------
65
66 Git does not have commitmentphobia. In fact, it loves commits as if it were its
67 only purpose in life.
68
69 In most if not all source code management software, a commit is essentially a
70 set of changes to be merged into the master repository.
71
72 To create a commit, there are several steps that need to take place.
73
74 Firstly, the changed files to be pushed to the repository need to be added. For
75 this, we use the _git add_ command.
76
77 ----
78 $ git add ./ex1.blah
79 $ git add ./example2.blah
80 ----
81
82 One handy bit for this is the _-A_ switch. If used, git will recursively add
83 all files in the specified directory that have been changed for the commit.
84 This is very handy if many files were changed.
85
86 ----
87 $ git add -A .
88 ----
89
90 Once the changes files are set up for commit, we just need one more step. Run
91 _git commit_ and you will be taken to a text editor (likely vi
92 - specified in the repository configuration) to add comments on your commit so
93 you and other developers know what was changed in your commit in case
94 something is broken or someone wants to revert.
95
96 _This piece is key if you are using the git repository as a code repository
97 rather than a versioning repository for backups. Please write in meaningful
98 comments._
99
100 There is actually one more piece to committing a change if you have a remote
101 repository on another box or a different location on the local box. So other
102 developers can pull the repository and get your changes, you need to _push_
103 your changes to the remote repository. Please see the
104 link:#Pushing_Changes_to_the_Remote_Repository[Pushing Changes to a Remote
105 Repository] section for more information on this. To do this, we use the _git
106 push_ command.
107
108
109 [[logs]]
110 Logs
111 ----
112
113 All of this commit and commit log business is a bit worthless if we can't look
114 at logs. To look at the logs we use the _git log_ command. This will open up
115 your system's pager (typically less is the one used) to view the logs for the
116 current branch. If you wish to view the logs on a different branch, you can
117 either check out that branch, or you can type __git log BranchName__.
118
119 A handy option for the _git log_ command is the _--name-status_ switch. If you
120 use this switch, git will list all of the commit logs along with all of the
121 files affected and what was done (modified, deleted, created, renamed) in each
122 individual commit.
123
124
125 [[remote-repositories]]
126 Remote Repositories
127 -------------------
128
129 Git is a distributed code versioning system which means that every person that
130 has pulled the repository has a complete copy of the original. This is really
131 great for working remotely because you don't have to be online and able to talk
132 to the remote repository to see change history.
133
134
135 [[adding-a-remote-repository]]
136 Adding a Remote Repository
137 ~~~~~~~~~~~~~~~~~~~~~~~~~~
138
139 Git needs several things to add a remote repository. Firstly, it needs a
140 local alias for the remote repository. It also needs a username to log
141 in to the repo with, as well as the ip address or hostname of the
142 repository, and the path to the actual repo directory on the remote
143 server. With that, to add a remote repository the command looks somewhat
144 like this:
145
146 ----
147 git remote add origin gitman@someserver.org:repos/CleverProjectName
148 ----
149
150 Now, let's break down what that all means since it seems a tad complicated.
151
152 [cols=",,,,,",options="header",]
153 |===========================================================================
154 |git remote |add |origin |gitman |@someserver.org | :repos/CleverProjectName
155 |This is the command to work with remote servers in git.
156 |Tells git we are adding a remote
157 |The local alias for the remote. Origin is typically used here.
158 |The username to log in to the remote server with.
159 |This is the server where the repo is stored
160 |This is the path to the actual repository directory. Since it does not start
161 with a / it starts in the home directory of gitman (~/).
162 |=======================================================================
163
164 [[fetching-a-remote-repository]]
165 Fetching a Remote Repository
166 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
167
168 Now that we have a remote repository added to our local git repository, we
169 simply need to fetch the repo. To do this we use the _git fetch_ command. Here
170 is where that alias from the remote add command comes in handy.
171
172 ----
173 git fetch origin
174 ----
175
176 This command will fetch all branches of the origin repository.
177
178 [[pushing-changes-to-the-remote-repository]]
179 Pushing Changes to the Remote Repository
180 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
181
182 Now that we have a local copy of a repository to work on and have made some
183 changes, some amount of code synchronization needs to take place with an origin
184 repository so each of the developers can have the latest-and-greatest. With
185 that, a commit only pushes code to your local copy of the repository. What
186 needs to happen after a commit is to push the change to the origin repository
187 so everyone else will also have access to your change set. To do this, we use
188 the _git push_ command.
189
190 There are two parameters for this though. The first is the local alias for the
191 remote repository (typically referred to as origin since presumably the remote
192 server is where your repository originated). The second parameter is the branch
193 name. Since we often have more than one branch, this is a good piece to pay
194 attention to so you don't submit a database dump file to the code branch.
195
196 ----
197 git push origin master
198 ----
199
200
201 [[dealing-with-size-issues]]
202 Dealing with Size Issues
203 ------------------------
204
205 Since git is a code versioning system that contains as many versions of a file
206 as the number of commits, its size can grow out of hand rather quickly,
207 especially when dealing with binaries. Luckily, there is a handy command for
208 this very situation: **git gc**.
209
210 This command compresses all of your repository branches in the context of each
211 other. This can reduce the size of your local and/or remote repositories very
212 effectively. I have a repository that should be several gigabytes with about 60
213 commits per branch (it's a repo used for versioned backups), and _git gc_
214 reduced it to about 370 megabytes.
215
216
217 Category:Git
218
219
220 // vim: set syntax=asciidoc:
|
