From 9bb559d5e2d5882fcdc376a2d6b45858a0fb1b80 Mon Sep 17 00:00:00 2001 From: Kern Sibbald Date: Mon, 10 Aug 2009 21:24:50 +0000 Subject: [PATCH] Update Developer's guid for git --- docs/manuals/en/developers/developers.kilepr | 6 +- docs/manuals/en/developers/developers.tex | 2 +- docs/manuals/en/developers/generaldevel.tex | 152 +++++++++++++++++-- 3 files changed, 146 insertions(+), 14 deletions(-) diff --git a/docs/manuals/en/developers/developers.kilepr b/docs/manuals/en/developers/developers.kilepr index 67f50e6a..0f0a87f3 100644 --- a/docs/manuals/en/developers/developers.kilepr +++ b/docs/manuals/en/developers/developers.kilepr @@ -47,7 +47,7 @@ archive=true column=0 encoding= highlight=LaTeX -line=0 +line=73 open=true order=1 @@ -80,10 +80,10 @@ order=-1 [item:generaldevel.tex] archive=true -column=2 +column=0 encoding= highlight=LaTeX -line=0 +line=603 open=true order=2 diff --git a/docs/manuals/en/developers/developers.tex b/docs/manuals/en/developers/developers.tex index 9fdf26c1..8f1c94d4 100644 --- a/docs/manuals/en/developers/developers.tex +++ b/docs/manuals/en/developers/developers.tex @@ -72,7 +72,7 @@ \pagenumbering{roman} \tableofcontents - +\pagenumbering{arabic} \include{generaldevel} \include{platformsupport} \include{daemonprotocol} diff --git a/docs/manuals/en/developers/generaldevel.tex b/docs/manuals/en/developers/generaldevel.tex index 34694e2e..9407ad10 100644 --- a/docs/manuals/en/developers/generaldevel.tex +++ b/docs/manuals/en/developers/generaldevel.tex @@ -391,11 +391,13 @@ As of August 2009, the Bacula source code has been split into two repositories. One is a GIT repository that holds the main Bacula source code with directories {\bf bacula}, {\bf gui}, and {\bf regress}. The second repository (SVN) contains -the directories {\bf rescue} and {\bf docs}. +the directories {\bf rescue} and {\bf docs}. Both repositories are +hosted on Source Forge. -We have split the previous SVN repository into two because GIT -offers enormous advantages for ease of managing and integrating -developer's changes. One of the disadvantages of GIT is that you +Previously everything was in a single SVN repository. +We have split the SVN repository into two because GIT +offers significant advantages for ease of managing and integrating +developer's changes. However, one of the disadvantages of GIT is that you must work with the full repository, while SVN allows you to checkout individual directories. If we put everything into a single GIT repository it would be far bigger than most developers would want @@ -404,7 +406,7 @@ repository, and moved only the parts that are most actively worked on by the developers (bacula, gui, and regress) to a GIT repository. -Unfortunately, this requires developers to have a certain knowledege +Unfortunately, Bacula developers must now have a certain knowledege of both GIT and SVN, and if you are a core Bacula developer knowledge of GIT is particularly important. @@ -426,15 +428,15 @@ For developers, the most important thing to remember about GIT and the Source Forge repository is not to "force" a {\bf push} to the repository, and not to use the {\bf rebase} command on the {\bf master} branch of the repository. Doing so, will possibly rewrite -the GIT repository history and possibly get your commit privileges -revoked. +the GIT repository history and cause a lot of problems for the +project. You may and should use {\bf rebase} on your own branches that you want to synchronize with the {\bf master} branch, but please do not use {\bf rebase} on the {\bf master} branch. The proper way of merging changes will be discussed below. -You can get a full copy of the Bacula GIT repository with the +You can get a full copy of the Source Forge Bacula GIT repository with the following command: \begin{verbatim} @@ -466,8 +468,138 @@ git pull origin As of August 2009, the size of the repository ({\bf trunk} in the above example) will be approximately 55 Megabytes. However, if you build from source in this directory and do a lot of updates and regression -testing, the directory could -become several hundred megabytes. +testing, the directory could become several hundred megabytes. + +\subsection{Learning GIT} +\index{Learning GIT} +If you want to learn more about GIT, we recommend that you visit:\\ +\elink{http://book.git-scm.com/}{http://book.git-scm.com/}. + + +\subsection{Publishing your changes} +\index{Publishing} +Since GIT is more complex than SVN, it takes a bit of time to learn how +to use it properly, and if you are not careful, you can potentially create +a new history in the repository. In addition, since GIT is a distributed +version control system, we prefer to receive a full branch submission rather +than simply a patch. To accomplish this, you must create your changes in +a branch, then {\bf push} them to some public repository -- it can be your +own repository that you publish or another. To simplify this phase for you, we +have created a publich Bacula GIT repository on {\bf github} where you can +push your branch containing changes you would like integrated into the Bacula +source code. + +Once you have pushed your branch to {\bf github} or told us where we can pull +from your public repository, one of the senior Bacula devlopers will fetch your +changes, examine them, possibly make comments for changes they would like to +see, and as the final step, the senior developer will commit it to the +Bacula Source Forge GIT repository. + +\subsection{Github} +\index{github} +If you are going to submit before cloning the Bacula Github database, you must create a login on +the Github website:\\ +\elink{http://github.com/}{http://github.com/}\\ +You must also upload your public ssh key. Please see the instructions +at the above link. Then you notify one of the senior Bacula developers, +who will add your Github user name to the Bacula repository. Finally, +you clone the Bacula repository with: + +\begin{verbatim} + git clone git@github.com:/bacula.git +\end{verbatim} + +where you replace \verb++ with the User Name that you created +when you created your Github login, and you replace \verb++ with the name +of a directory that you want git to create to hold your local Bacula git +repository. + +Normally, you will work by creating a branch of the master branch of your +repository, make your modifications, then make sure it is up to date, and finally +push it to Github. Assuming you call the Bacula repository {\bf bacula}, you might +use the following commands: + +\begin{verbatim} +cd bacula +git checkout master +git pull +git branch /newbranch +git checkout /newbranch +(edit, ...) +git add +git commit -m "" +... +\end{verbatim} + +Note, we request you to create the branch name with your github +login name. This guarantees that the branch name will be unique and +easily identified as well. + +When you have completed working on your branch, you will do: + +\begin{verbatim} +cd bacula +git checkout /newbranch +git pull +git rebase master +\end{verbatim} + +If you have completed your edits before anyone has modified the repository, +the {\bf git rebase master} will report that there was nothing to do. Otherwise, +it will merge the changes that were made in the repository before your changes. +If there are any conflicts, git will tell you. Typically resolving conflicts with +git is relatively easy. You simply make a diff: + +\begin{verbatim} +git diff +\end{verbatim} + +Then edit each file that was listed in the {\bf git diff} to remove the +conflict, which will be indicated by lines of: + +\begin{verbatim} +<<<<<<< HEAD +text +>>>>>>>> +other text +===== +\end{verbatim} + +where {\bf text} is what is in the Bacula repository, and {\bf other text} +is what you have changed. + +Once you have eliminated the conflict, the {\bf git diff} will show nothing, +and you must do a: + +\begin{verbatim} +git add +\end{verbatim} + +Once you have fixed all the files with conflicts in the above manner, you enter: + +\begin{verbatim} +git rebase --continue +\end{verbatim} + +and your rebase will be complete. + +If for some reason, before doing the --continue, you want to abort the rebase and return to what you had, you enter: + +\begin{verbatim} +git rebase --abort +\end{verbatim} + +Finally to upload your branch, you do: + +\begin{verbatim} +git push origin /newbranch +\end{verbatim} + +If you wish to delete it later, you can use: + +\begin{verbatim} +git push origin :/newbranch +\end{verbatim} -- 2.39.5