phpBB

Development Wiki

Difference between revisions of "Working with Git"

From phpBB Development Wiki

Redirect page
(Further reading: getting git - change description)
(Redirected page to Git)
 
(26 intermediate revisions by 8 users not shown)
Line 1: Line 1:
This gives some documentation on using git for phpBB development, details of the phpBB [[Git|git infrastructure]] documents the repositories and branches available for use.
+
#REDIRECT [[Git]]
 
+
= Command Line =
+
 
+
== Basics ==
+
 
+
=== Cloning ===
+
Clone the main phpBB3 repository.
+
<pre>git clone git://github.com/phpbb/phpbb3.git</pre>
+
 
+
=== Branches ===
+
 
+
See [[Git#Branches|phpBB3 Branches]]
+
 
+
== Developers ==
+
 
+
Developers should fork a copy of the repository on GitHub from [http://github.com/phpbb/phpbb3] and then clone as instructed by GitHub.
+
 
+
=== Configuration ===
+
* E-mail address: <pre>git config --add user.email username@phpbb.com</pre>
+
* Add the upstream remote (you can change 'upstream' to whatever you like): <pre>git remote add upstream git://github.com/phpbb/phpbb3.git</pre>
+
 
+
=== Creating local branches ===
+
To work on phpBB you need to create local branches of whichever '''develop''' branches you need, issue the following command to perform this operation:
+
<pre>git checkout -b develop origin/develop</pre>
+
 
+
=== Workflows ===
+
 
+
==== Pulling in upstream changes ====
+
You will need to merge in changes made to the upstream repository for them to appear in your fork, the steps to do this follow. I'm assuming you are performing this on the '''develop''' branch, but it could be a bug fix branch or a develop release branch, so ensure you are on the correct branch using git branch and change with git checkout if required.
+
 
+
# Pull the changes from the upstream '''develop''' branch: <pre>git pull upstream develop</pre>
+
# Push the changes back to your fork (substitute develop for the current branch): <pre>git push origin develop</pre>
+
 
+
The following image visualises the phpBB 3 branching model. It may help to understand the different branches this section refers to later.
+
 
+
[[File:Phpbb-git-workflow-small.png]]
+
 
+
View in [[Media:Phpbb-git-workflow.png|large]] or as [[Media:Phpbb-git-workflow.svg|svg]].
+
 
+
==== Bug fixing ====
+
Ensure you are using the correct ''develop'' branch first and not a ''master'' branch.  In this example we are using develop-olympus.
+
 
+
# git checkout develop-olympus # Checkout the base branch
+
# git branch bug/12345 # Create a new branch for your bug fix
+
# git checkout bug/12345 # Switch to the new branch
+
# Make your changes
+
# git add <files> # Stage the files
+
# git commit # Commit staged files - please use a correct commit message: [[Git#Commit_Messages|Git Commit Messages]]
+
# Make more changes & commits if necessary
+
# git push origin bug/12345 # Push the branch back to github
+
 
+
==== Starting a new feature ====
+
Ensure you are using the correct ''develop'' branch first and not a ''master'' branch.  In this example we are using develop.
+
 
+
# git checkout develop # Checkout the base branch
+
# git checkout -b feature/my-fancy-new-feature # Create a new branch for your feature & switch to it
+
# Make your changes
+
# git add <files> # Stage the files
+
# git commit # Commit staged files - please use a correct commit message: [[Git#Commit_Messages|Git Commit Messages]]
+
# Make more changes & commits
+
# git push origin feature/my-fancy-new-feature # Push the branch back to github
+
 
+
==== Collaborating with other developers on a feature ====
+
You have pushed a new feature to github and another developer has worked on it. This is how you can integrate their changes into your own feature branch.
+
 
+
# git remote add otherdeveloper git://github.com/otherdeveloper/phpbb3.git # Add the other developer's repository as a remote
+
# git fetch otherdeveloper # Fetch otherdeveloper's changes
+
# git checkout feature/my-fancy-new-feature # Switch to the feature branch
+
# git merge otherdeveloper/feature/my-fancy-new-feature # Merge otherdeveloper's changes into your feature branch
+
# If necessary resolve conflicts & commit
+
# git push origin feature/my-fancy-new-feature # Push the branch back to github
+
 
+
==== Merging a feature or bugfix branch ====
+
Once a feature or bugfix is complete it can be merged back into the develop branch. To preserve history we never fast forward such merges. In this example we will merge the bugfix created earlier into develop-olympus. We then merge the changes into develop to keep that branch up to date.
+
 
+
# git checkout develop-olympus # Branch we want to merge into
+
# git merge --no-ff bug/12345 # Merge, but do not fast forward
+
# git branch -d bug/12345 # Delete the bugfix branch
+
# git checkout develop # Switch to develop
+
# git merge --no-ff develop-olympus # Merge to keep the develop branches in sync
+
# git push origin develop-olympus # Push the develop-olympus branch back to github
+
# git push origin develop # Push the develop-olympus branch back to github
+
# git push origin :bug/12345 # Remove the bug fix branch from github
+
 
+
= Windows =
+
Quick info for those with [http://code.google.com/p/tortoisegit/ TortoiseGit] (and used to working with TortoiseSVN)
+
 
+
== Create your own SSH key ==
+
 
+
http://help.github.com/msysgit-key-setup/
+
 
+
TortoiseGit will automatically use the SSH key
+
 
+
''Note: I used the OpenSSH option during installation, so I am not sure if this works for the other option or if you are supposed to do it some other way''
+
 
+
== Clone ==
+
 
+
Then simply clone the repository to your local system and the rest is mostly like TortoiseSVN.
+
 
+
== Commands ==
+
 
+
;Pull
+
:Grab the updates from upstream
+
 
+
;Commit
+
:Commits the changes '''locally''' (you must Push or Sync to commit the changes to the repository)
+
 
+
;Push
+
:Pushes the changes that were locally made into the repository
+
 
+
;Sync
+
:Pushes/Pulls changes with more options
+
 
+
= Further reading =
+
 
+
* [http://progit.org/book/ Pro Git Book (online)]
+
* [http://gitcasts.com/ GitCasts]
+
* [http://gitcasts.com/posts/railsconf-git-talk Getting Git] - RailsConf Git Talk by Scott Chacon
+
* [http://git-scm.com/documentation Official Git Documentation]
+
* [http://git-scm.com/course/svn.html Git Crash Course for SVN users]
+
* [http://github.com/guides/home GitHub Guides]
+
 
+
= External links =
+
 
+
* [http://git-scm.com/ Official Git homepage]
+
* [http://github.com/ GitHub]
+
* [http://github.com/phpbb phpBB GitHub account]
+
* [http://code.google.com/p/tortoisegit/ TortoiseGIT] - A windows Git client based on TortoiseSVN
+
 
+
[[Category:Development|Git]]
+
[[Category:Tutorials]]
+

Latest revision as of 14:04, 20 March 2012