1 \chapter{Bacula Git Usage}
2 \label{_GitChapterStart}
5 \addcontentsline{toc}{section}{Bacula Bit Usage}
7 This chapter is intended to help you use the Git source code
8 repositories to obtain, modify, and submit Bacula source code.
11 \section{Bacula Git repositories}
13 \addcontentsline{toc}{subsection}{Git repositories}
14 As of September 2009, the Bacula source code has been split into
15 three Git repositories. One is a repository that holds the
16 main Bacula source code with directories {\bf bacula}, {\bf gui},
17 and {\bf regress}. The second repository contains
18 the directories {\bf docs} directory, and the third repository
19 contains the {\bf rescue} directory. All three repositories are
20 hosted on Source Forge.
22 Previously everything was in a single SVN repository.
23 We have split the SVN repository into three because Git
24 offers significant advantages for ease of managing and integrating
25 developer's changes. However, one of the disadvantages of Git is that you
26 must work with the full repository, while SVN allows you to checkout
27 individual directories. If we put everything into a single Git
28 repository it would be far bigger than most developers would want
29 to checkout, so we have separted the docs and rescue into their own
30 repositories, and moved only the parts that are most actively
31 worked on by the developers (bacula, gui, and regress) to a the
32 Git Bacula repository.
34 Bacula developers must now have a certain knowledege of Git.
38 \addcontentsline{toc}{subsection}{Git Usage}
40 Please note that if you are familiar with SVN, Git is similar,
41 (and better), but there can be a few surprising differences that
42 can be very confusing (nothing worse than converting from CVS to SVN).
44 The main Bacula Git repo contains the subdirectories {\bf bacula}, {\bf gui},
45 and {\bf regress}. With Git it is not possible to pull only a
46 single directory, because of the hash code nature of Git, you
47 must take all or nothing.
49 For developers, the most important thing to remember about Git and
50 the Source Forge repository is not to "force" a {\bf push} to the
51 repository. Doing so, can possibly rewrite
52 the Git repository history and cause a lot of problems for the
55 You can get a full copy of the Source Forge Bacula Git repository with the
59 git clone git://bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
62 This will put a read-only copy into the directory {\bf trunk}
63 in your current directory, and {\bf trunk} will contain
64 the subdirectories: {\bf bacula}, {\bf gui}, and {\bf regress}.
65 Obviously you can use any name an not just {\bf trunk}. In fact,
66 once you have the repository in say {\bf trunk}, you can copy the
67 whole directory to another place and have a fully functional
70 If you have write permission to the Source Forge
71 repository, you can get a copy of the Git repo with:
74 git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
77 where you replace \verb+<userid>+ with your Source Forge login
78 userid, and you must have previously uploaded your public ssh key
81 The above command needs to be done only once. Thereafter, you can:
85 git pull # refresh my repo with the latest code
88 As of August 2009, the size of the repository ({\bf trunk} in the above
89 example) will be approximately 55 Megabytes. However, if you build
90 from source in this directory and do a lot of updates and regression
91 testing, the directory could become several hundred megabytes.
93 \subsection{Learning Git}
95 If you want to learn more about Git, we recommend that you visit:\\
96 \elink{http://book.git-scm.com/}{http://book.git-scm.com/}.
98 Some of the differences between Git and SVN are:
100 \item Your main Git directory is a full Git repository to which you can
101 and must commit. In fact, we suggest you commit frequently.
102 \item When you commit, the commit goes into your local Git
103 database. You must use another command to write it to the
104 master Source Forge repository (see below).
105 \item The local Git database is kept in the directory {\bf .git} at the
106 top level of the directory.
107 \item All the important Git configuration information is kept in the
108 file {\bf .git/config} in ASCII format that is easy to manually edit.
109 \item When you do a {\bf commit} the changes are put in {\bf .git}
110 rather but not in the main Source Forge repository.
111 \item You can push your changes to the external repository using
112 the command {\bf git push} providing you have write permission
114 \item We restrict developers just learning git to have read-only
115 access until they feel comfortable with git before giving them
117 \item You can download all the current changes in the external repository
118 and merge them into your {\bf master} branch using the command
120 \item The command {\bf git add} is used to add a new file to the
121 repository AND to tell Git that you want a file that has changed
122 to be in the next commit. This has lots of advantages, because
123 a {\bf git commit} only commits those files that have been
124 explicitly added. Note with SVN {\bf add} is used only
125 to add new files to the repo.
126 \item You can add and commit all files modifed in one command
127 using {\bf git commit -a}.
128 \item This extra use of {\bf add} allows you to make a number
129 of changes then add only a few of the files and commit them,
130 then add more files and commit them until you have committed
131 everything. This has the advantage of allowing you to more
132 easily group small changes and do individaual commits on them.
133 By keeping commits smaller, and separated into topics, it makes
134 it much easier to later select certain commits for backporting.
135 \item If you {\bf git pull} from the main repository and make
136 some changes, and before you do a {\bf git push} someone
137 else pushes changes to the Git repository, your changes will
138 apply to an older version of the repository you will probably
139 get an error message such as:
143 To git@github.com:bacula/bacula.git
144 ! [rejected] master -> master (non-fast forward)
145 error: failed to push some refs to 'git@github.com:bacula/bacula.git'
148 which is Git's way of telling you that the main repository has changed
149 and that if you push your changes, they will not be integrated properly.
150 This is very similar to what happens when you do an "svn update" and
152 As we have noted above, you should never ask Git to force the push.
153 See below for an explanation of why.
154 \item To integrate (merge) your changes properly, you should always do
155 a {\bf git pull} just prior to doing a {\bf git push}.
156 \item If Git is unable to merge your changes or finds a conflict it
157 will tell you and you must do conflict resolution, which is much
158 easier in Git than in SVN.
159 \item Resolving conflicts is described below in the {\bf github} section.
162 \section{Step by Step Modifying Bacula Code}
163 Suppose you want to download Bacula source code, build it, make
164 a change, then submit your change to the Bacula developers. What
168 \item Download the Source code:\\
170 git clone ssh://<userid>@bacula.git.sourceforge.net/gitroot/bacula/bacula trunk
173 \item Configure and Build Bacula:\\
175 ./configure (all-your-normal-options)
179 \item Create a branch to work on:
182 git checkout -b bugfix master
185 \item Edit, build, Test, ...\\
192 \item commit your work:
194 git commit -am "Short comment on what I did"
197 \item Possibly repeat the above two items
199 \item Switch back to the master branch:\\
204 \item Pull the latest changes:\\
209 \item Get back on your bugfix branch:\\
214 \item Merge your changes and correct any conflicts:\\
216 git rebase master bugfix
219 \item Fix any conflicts:\\
220 You will be notified if there are conflicts. The first
227 This will produce a diff of only the files having a conflict.
228 Fix each file in turn. When it is fixed, the diff for that file
231 For each file fixed, you must do the same as SVN, inform git with:
234 git add (name-of-file-no-longer-in-conflict)
237 \item When all files are fixed do:
239 git rebase --continue
242 \item When you are ready to send a patch, do the following:\\
245 git format-patch -M master
247 Look at the files produced. They should be numbered 0001-xxx.patch
248 where there is one file for each commit you did, number sequentially,
249 and the xxx is what you put in the commit comment.
251 \item If the patch files are good, send them by email to the developers
258 \subsection{More Details}
260 Normally, you will work by creating a branch of the master branch of your
261 repository, make your modifications, then make sure it is up to date, and finally
262 create format-patch patches or push it to the Source Forge repo. Assuming
263 you call the Bacula repository {\bf trunk}, you might use the following
270 git checkout -b newbranch master
272 git add <file-edited>
273 git commit -m "<comment about commit>"
277 When you have completed working on your branch, you will do:
281 git checkout newbranch # ensure I am on my branch
282 git pull # get latest source code
283 git rebase master # merge my code
286 If you have completed your edits before anyone has modified the repository,
287 the {\bf git rebase master} will report that there was nothing to do. Otherwise,
288 it will merge the changes that were made in the repository before your changes.
289 If there are any conflicts, Git will tell you. Typically resolving conflicts with
290 Git is relatively easy. You simply make a diff:
296 Then edit each file that was listed in the {\bf git diff} to remove the
297 conflict, which will be indicated by lines of:
307 where {\bf text} is what is in the Bacula repository, and {\bf other text}
308 is what you have changed.
310 Once you have eliminated the conflict, the {\bf git diff} will show nothing,
314 git add <file-with-conflicts-fixed>
317 Once you have fixed all the files with conflicts in the above manner, you enter:
320 git rebase --continue
323 and your rebase will be complete.
325 If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter:
331 Finally to make a set of patch files
334 git format-patch -M master
337 When you see your changes have been integrated and pushed to the
338 main repo, you can delete your branch with:
342 git branch -D newbranch
346 \section{Forcing Changes}
347 If you want to understand why it is not a good idea to force a
348 push to the repository, look at the following picture:
350 \includegraphics[width=0.85\textwidth]{\idir git-edit-commit.eps}
352 The above graphic has three lines of circles. Each circle represents
353 a commit, and time runs from the left to the right. The top line
354 shows the repository just before you are going to do a push. Note the
355 point at which you pulled is the circle on the left, your changes are
356 represented by the circle labeled {\bf Your mods}. It is shown below
357 to indicate that the changes are only in your local repository. Finally,
358 there are pushes A and B that came after the time at which you pulled.
360 If you were to force your changes into the repository, Git would place them
361 immediately after the point at which you pulled them, so they would
362 go before the pushes A and B. However, doing so would rewrite the history
363 of the repository and make it very difficult for other users to synchronize
364 since they would have to somehow wedge their changes at some point before the
365 current HEAD of the repository. This situation is shown by the second line of
368 What you really want to do is to put your changes after Push B (the current HEAD).
369 This is shown in the third line of pushes. The best way to accomplish this is to
370 work in a branch, pull the repository so you have your master equal to HEAD (in first
371 line), then to rebase your branch on the current master and then commit it. The
372 exact commands to accomplish this are shown in the next couple of sections.