|
|
| Line 1: |
Line 1: |
| __NOTOC__
| |
|
| |
|
| This page documents how to develop TubeTK through [http://git-scm.com Git].
| |
| See our [[TubeTK/Git|table of contents]] for more information.
| |
|
| |
| <i>
| |
| Git is an extremely powerful version control tool that supports many different "workflows" for indivudal development and collaboration.
| |
| Here we document procedures used by the TubeTK development community.
| |
| In the interest of simplicity and brevity we do '''not''' provide an explanation of why we use this approach.
| |
| Furthermore, this is '''not''' a Git tutorial.
| |
| Please see our [[Git/Resources|Git resource links]] for third-party documentation, such as the [http://git-scm.com/book/ ProGit Book].
| |
| </i>
| |
|
| |
| =Setup=
| |
|
| |
| Before you begin, perform initial setup:
| |
|
| |
| {| style="width: 100%" cellspacing="0" cellpadding="0"
| |
| |-
| |
| |width=60%|
| |
| 1.
| |
| Register [[TubeTK/Git/Account#Gerrit|Gerrit access]] and possibly [[TubeTK/Git/Account#Git|Git push access]].
| |
| |-
| |
| |
| |
| 2.
| |
| Follow the [[TubeTK/Git/Download#Clone|download instructions]] to create a local TubeTK clone:
| |
| |-
| |
| |
| |
| :<code>$ git clone git://tubetk.org/TubeTK.git</code>
| |
| |align="center"|
| |
| [[Git/Trouble#Firewall_Blocks_Port_9418|Connection refused]]?
| |
| |-
| |
| |
| |
| 3.
| |
| Run the developer setup script to prepare your TubeTK work tree and create Git command aliases used below:
| |
| |-
| |
| |
| |
| :<code>$ ./Utilities/SetupForDevelopment.sh</code>
| |
| |align="center"|
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/SetupForDevelopment.sh;hb=HEAD <code>SetupForDevelopment.sh</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Getting-Started-First-Time-Git-Setup Pro Git: Setup]
| |
| |}
| |
|
| |
| =Workflow=
| |
|
| |
| TubeTK development uses a [[Git/Workflow/Topic|branchy workflow]] based on topic branches.
| |
| Our collaboration workflow consists of three main steps:
| |
|
| |
| {| style="width: 100%" cellspacing="0" cellpadding="0"
| |
| |-
| |
| |width=60%|
| |
| 1.
| |
| Local Development
| |
| |-
| |
| |
| |
| :* [[#Update|Update]]
| |
| |-
| |
| |
| |
| :* [[#Create_a_Topic|Create a Topic]]
| |
| |-
| |
| |
| |
| 2.
| |
| Code Review
| |
| |-
| |
| |
| |
| :* [[#Share_a_Topic|Share a Topic]] (requires [[TubeTK/Git/Account#Git|Git push access]])
| |
| |-
| |
| |
| |
| :* [[#Revise_a_Topic|Revise a Topic]]
| |
| |-
| |
| |
| |
| 3.
| |
| Integrate Changes
| |
| |-
| |
| |
| |
| :* [[#Merge_a_Topic|Merge a Topic]] (requires [[TubeTK/Git/Account#Git|Git push access]])
| |
| |-
| |
| |
| |
| :* [[#Delete_a_Topic|Delete a Topic]]
| |
| |}
| |
|
| |
| ==Update==
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Update your local '''master''' branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout master</code>
| |
| :<code>$ git pullall</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-pull.html <code>pull</code>] and
| |
| [http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)
| |
| |}
| |
|
| |
| ==Create a Topic==
| |
|
| |
| All new work must be committed on topic branches.
| |
| Name topics like you might name functions: concise but precise.
| |
| A reader should have a general idea of the feature or fix to be developed given just the branch name.
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| To start a new topic branch:
| |
| |-
| |
| |
| |
| :<code>$ git fetch origin</code>
| |
| :<code>$ git checkout -b ''my-topic'' origin/master</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-submodule.html <code>git help submodule</code>]
| |
| |-
| |
| |
| |
| Edit files and create commits (repeat as needed):
| |
| |-
| |
| |
| |
| :<code>$ edit ''file1'' ''file2'' ''file3''</code>
| |
| :<code>$ git add ''file1'' ''file2'' ''file3''</code>
| |
| :<code>$ git commit</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-add.html <code>git help add</code>]
| |
| <br/>
| |
| [http://schacon.github.com/git/git-commit.html <code>git help commit</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Git-Basics-Recording-Changes-to-the-Repository Pro Git: Recording Changes]
| |
| |}
| |
|
| |
| ==Share a Topic==
| |
|
| |
| ===On Gerrit===
| |
|
| |
| When a topic is ready for review and possible inclusion, share it by pushing to Gerrit.
| |
| Be sure you have registered for [[TubeTK/Git/Account#Gerrit|Gerrit access]].
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout the topic if it is not your current branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| |-
| |
| |
| |
| Check what commits will be pushed to Gerrit for review:
| |
| |-
| |
| |
| |
| :<code>$ git prepush</code>
| |
| |align="center"|
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/GitSetup/setup-aliases;hb=HEAD <code>alias.prepush</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)
| |
| |-
| |
| |
| |
| Push commits in your topic branch for review by the community:
| |
| |-
| |
| |
| |
| :<code>$ git gerrit-push</code>
| |
| |align="center"|
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/GitSetup/setup-aliases;hb=HEAD <code>alias.gerrit-push</code>]
| |
| <br/>
| |
| ([http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/GitSetup/git-gerrit-push;hb=HEAD <code>Utilities/GitSetup/git-gerrit-push</code>])
| |
| |}
| |
| Find your change in the [http://review.source.kitware.com/p/TubeTK TubeTK Gerrit] instance and add [[TubeTK/Gerrit/Reviewers|reviewers]].
| |
|
| |
| ===On the stage repository===
| |
|
| |
| When a topic is ready for review and possible inclusion, share it by pushing to the [[Git/Workflow/Stage|topic stage]].
| |
| '''Only authorized developers with [[TubeTK/Git/Account#Git|Git push access]] to <code>tubetk.org</code> may perform this step.'''
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout the topic if it is not your current branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| |-
| |
| |
| |
| Check what commits will be pushed to the topic stage:
| |
| |-
| |
| |
| |
| :<code>$ git prepush</code>
| |
| |align="center"|
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.prepush</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-log.html <code>log</code>] <code>origin/master..</code>)
| |
| |-
| |
| |
| |
| Push commits in your topic branch to the topic stage:
| |
| |-
| |
| |
| |
| :<code>$ git stage-push</code>
| |
| |align="center"|
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.stage-push</code>]
| |
| |-
| |
| |
| |
| The topic is now published on the [http://tubetk.org/stage/TubeTK.git TubeTK Topic Stage] and may be (optionally) reviewed by others.
| |
| To fetch staged topics for review, run
| |
| |-
| |
| |
| |
| :<code>$ git fetch stage --prune</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-fetch.html <code>git help fetch</code>]
| |
| |}
| |
|
| |
| ==Revise a Topic==
| |
|
| |
| If a topic is approved after review, skip to the [[#Merge_a_Topic|next step]].
| |
| Otherwise, revise the topic and push it back to the topic stage for another review.
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout the topic if it is not your current branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| |
| |
| |-
| |
| |
| |
| or
| |
| |
| |
| |-
| |
| |
| |
| :<code>$ git branch --set-upstream "staged-topic" stage/"staged-topic"</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-branch.html <code>git help branch</code>]
| |
| |
| |
| |-
| |
| |
| |
| To revise the most recent commit on the topic edit files and add changes normally and then amend the commit:
| |
| |-
| |
| |
| |
| :<code>$ git commit --amend</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-commit.html <code>git help commit</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-the-Last-Commit Pro Git: Changing the Last Commit]
| |
| |-
| |
| |
| |
| To revise the <code>3</code>rd commit back on the topic:
| |
| |-
| |
| |
| |
| :<code>$ git rebase -i HEAD~3</code>
| |
| ''(Substitute the correct number of commits back, as low as ''<code>1</code>''.)''
| |
|
| |
| Follow Git's interactive instructions.
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-rebase.html <code>git help rebase</code>]
| |
| <br/>
| |
| [http://git-scm.com/book/en/Git-Branching-Rebasing Pro Git: Rebasing]
| |
| |-
| |
| |
| |
| Return to the [[#Share_a_Topic|previous step]] to share the revised topic.
| |
| |}
| |
|
| |
| ==Merge a Topic==
| |
|
| |
| After a topic has been reviewed and approved, merge it into the upstream repository.
| |
| '''Only authorized developers with [[TubeTK/Git/Account#Git|Git push access]] to <code>tubetk.org</code> may perform this step.'''
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout the topic if it is not your current branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| |-
| |
| |
| |
| Merge the topic:
| |
| |-
| |
| |
| |
| :<code>$ git stage-merge</code>
| |
| :''(If the merge conflicts follow the printed instructions to resolve them.)''
| |
| |align="center"|
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.stage-merge</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-push.html <code>push</code>] to [[Git/Workflow/Stage|topic stage]] and
| |
| <br/>
| |
| <code>stage TubeTK merge ''my-topic''</code>)
| |
| <br/>
| |
| [[Git/Workflow/Topic/Conflicts#Branch-to-Topic|Branch-to-Topic Conflict Resolution]]
| |
| |}
| |
|
| |
| ==Delete a Topic==
| |
|
| |
| After a topic has been merged upstream, delete your local branch for the topic.
| |
|
| |
| {| style="width: 100%"
| |
| |-
| |
| |width=60%|
| |
| Checkout and update the '''master''' branch:
| |
| |-
| |
| |
| |
| :<code>$ git checkout master</code>
| |
| :<code>$ git pullall</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-checkout.html <code>git help checkout</code>]
| |
| <br/>
| |
| [http://tubetk.org/gitweb?p=TubeTK.git;a=blob;f=Utilities/Scripts/SetupGitAliases.sh;hb=HEAD <code>alias.pullall</code>]
| |
| <br/>
| |
| ([http://schacon.github.com/git/git-pull.html <code>pull</code>] and
| |
| [http://schacon.github.com/git/git-submodule.html <code>submodule</code>] <code>update</code>)
| |
| |-
| |
| |
| |
| Delete the local topic branch:
| |
| |-
| |
| |
| |
| :<code>$ git branch -d ''my-topic''</code>
| |
| |align="center"|
| |
| [http://schacon.github.com/git/git-branch.html <code>git help branch</code>]
| |
| |-
| |
| |
| |
| The <code>branch -d</code> command works only when the topic branch has been correctly merged.
| |
| Use <code>-D</code> instead of <code>-d</code> to force the deletion of an unmerged topic branch
| |
| (warning - you could lose commits).
| |
| |}
| |
|
| |
| [[Category:TubeTK]]
| |
