| ## Using Tickets | |
| *SINCE 1.4.0* | |
| ### Creating Standard Tickets | |
| Standard tickets can be created using the web ui. These ticket types include *Bug*, *Enhancement*, *task*, and *Question*. | |
| ### Creating a Proposal Ticket | |
| Proposal tickets are created by pushing a **single commit** to the magic ref. They can not be created from the web ui. | |
| *Why is there a single commit limitation for creating a Proposal Ticket?* | |
| Because the ticket which will be created for your commit will use your commit's message to define the Ticket's *title* and *description*. After the ticket is created, you can add as many commits as you want to the ticket's branch. | |
| *Why would I create a proposal ticket?* | |
| Because you are too lazy to create a ticket in the web ui first. The proposal ticket is a convenience mechanism. It allows you to propose a change using Git, not your browser. | |
| *Who can create a proposal ticket?* | |
| Any authenticated user who can clone your repository. | |
| git clone https://server/r/repo.git | |
| cd repo | |
| git checkout -b mytopic | |
| ...add a single commit... | |
| git push origin HEAD:refs/for/new | |
| # read ticket id from server output | |
| git branch -u origin/ticket/{id} | |
| ### Creating the first Patchset for an Existing Ticket | |
| If you have an existing ticket that does **not** yet have a proposed patchset you can push using the ticket branch ref. | |
| *Who can create the first patchset for an existing ticket?* | |
| Any authenticated user who can clone your repository. | |
| git clone https://server/r/repo.git | |
| cd repo | |
| git checkout -b ticket/{id} | |
| ...add one or more commits... | |
| git push -u origin ticket/{id} | |
| ### Safely adding commits to a Patchset for an Existing Ticket | |
| *Who can add commits to an existing patchset?* | |
| 1. The ticket author | |
| 2. The initial patchset author | |
| 3. The person set as *responsible* | |
| 4. Any user with write (RW) permissions to the repository | |
| git fetch && git checkout ticket/{id} | |
| git pull --ff-only | |
| ...add one or more commits... | |
| git push | |
| ### Rewriting a Patchset (amend, rebase, squash) | |
| *Who can rewrite a patchset?* | |
| See the above rules for who can add commits to a patchset. You do **not** need rewind (RW+) to the repository to push a non-fast-forward patchset. Gitblit will detect the non-fast-forward update and create a new patchset ref. This preserves the previous patchset. | |
| git fetch && git checkout ticket/{id} | |
| git pull --ff-only | |
| ...amend, rebase, squash... | |
| git push origin HEAD:refs/for/{id} | |
| OR if you have RW+ permissions, then you can push using *-f* flag. | |
| git push -f | |
| ### Updating your copy of a rewritten Patchset | |
| If a patchset has been rewritten you can no longer simply *pull* to update. Let's assume your checkout **does not** have any unshared commits - i.e. it represents the previous patchset. The simplest way to update your branch to the current patchset is to reset it. | |
| git fetch && git checkout ticket/{id} | |
| git reset --hard origin/ticket/{id} | |
| If you **do** have unshared commits then you'll could make a new temporary branch and then cherry-pick your changes onto the rewritten patchset. | |
| git branch oldticket ticket/{id} | |
| git fetch && git checkout ticket/{id} | |
| git reset --hard origin/ticket/{id} | |
| git cherry-pick <commitid1> <commitid2> | |
| git branch -D oldticket | |
| Git is a very flexible tool, there are no doubt several other strategies you could use to resolve this situation. The above solution is just one way. | |
| ### Ticket RefSpecs | |
| Gitblit supports two primary push ref specs: the magic ref and the patchset ref. | |
| #### to create a new proposal ticket | |
| | ref | description | | |
| | :------------------- | :------------------------------------------- | | |
| | refs/for/new | new proposal for the default branch | | |
| | refs/for/default | new proposal for the default branch | | |
| | refs/for/{branch} | new proposal for the specified branch | | |
| #### to add a proposal patchset (first patchset) to an existing ticket | |
| | ref | description | | |
| | :------------------- | :------------------------------------------- | | |
| | refs/for/{id} | add new patchset to an existing ticket | | |
| #### to add commits to an existing patchset | |
| | ref | description | | |
| | :--------------------------- | :----------------------------------- | | |
| | refs/heads/ticket/{id} | fast-forward an existing patchset | | |
| #### to rewrite a patchset (amend, rebase, squash) | |
| | magic ref | description | | |
| | :------------------- | :------------------------------------------- | | |
| | refs/for/{id} | to rewrite a patchset | | |
| ### Ticket RefSpec Tricks | |
| Gitblit supports setting some ticket fields from the push refspec. | |
| refs/for/master%topic=bug/42,r=james,m=1.4.1,cc=dave,cc=mark | |
| | parameter | description | | |
| | :-------- | :-------------------------------------------------------------- | | |
| | t | assign a *topic* to the ticket (matched against bugtraq config) | | |
| | r | set the *responsible* user | | |
| | m | set the *milestone* for patchset integration | | |
| | cc | add this account to the *watch* list (multiple ccs allowed) | | |
| #### examples | |
| Create a new patchset for ticket *12*, add *james* and *mark* to the watch list, and set the topic to *JIRA-123* which will be regex-matched against the repository bugtraq configuration. | |
| git push origin HEAD:refs/for/12%cc=james,cc=mark,t=JIRA-123 | |
| Add some commits (fast-forward) to ticket *12*. Set the milestone to *1.4.1*. | |
| git push origin HEAD:refs/heads/ticket/12%m=1.4.1 | |
| ### Merging Patchsets | |
| The Gitblit web ui offers a merge button which will work for clean merges of a patchset to the integration branch. | |
| There are complicated merge scenarios for which it may be best to merge using your Git client. There are several ways to do this, here is a safe merge strategy which pulls into a new branch and then fast-forwards your integration branch, assuming you were happy with the pull (merge). | |
| git pull origin master | |
| git checkout -b ticket-{id} master | |
| git pull origin ticket/{id} | |
| git checkout master | |
| git merge ticket-{id} | |
| git push origin master | |
| git branch -d ticket-{id} | |
| ### Closing Tickets on Push with a Completely New Patchset | |
| Gitblit will look for patchset references on pushes to normal branches. If it finds a reference (like would be found in the previous merge instructions), the ticket is resolved as merged and everyone is notified. | |
| If you do not need to create a patchset for review, you can just push a commit to the integration branch that contains `fixes #1` or `closes #1` in the commit message. Gitblit will identify the ticket, create a new patchset with that commit as the tip, and resolve the ticket as merged. (And if the integration branch is not specified in the ticket - this is the case for a ticket without any existing patchsets - Gitblit will resolve the ticket as merged to the pushed branch). | |
| ### Reopening Tickets with Patchsets | |
| Gitblit allows you to reopen a Ticket with a merged patchset. Since Gitblit allows patchset rewrites and versions patchsets, this seems like a logical capability. There is no need to create another ticket for a feature request or bug report if the merged commits did not actually resolve the ticket. | |
| This allows you to continue the discussion and create a new patchset that hopefully resolves the need. | |
| **NOTE:** There is one caveat to this feature. You can not push patchsets to a closed ticket; Gitblit will reject the push. You must first reopen the ticket through the web ui before you may push your patchset update or new patchset. | |
| ### Reviews | |
| Gitblit includes a very simple patchset scoring mechanism. Gitblit is not code-review system, but for those who have simple needs, this may suffice. | |
| - +2, approved: patchset can be merged | |
| - +1, looks good: someone else must approve for merge | |
| - -1, needs improvement: please do not merge | |
| - -2, vetoed: patchset may not be merged | |
| Only users with write (RW) permissions to the repository can give a +2 and -2 score. All other users are allowed to score +/-1. If the repository is configured to *require approval* then then +2 score has an important meaning. The merge button will only be shown if there is at least one +2 score and no -2 scores. If there is a -2 score, the merge is blocked by the web ui. Users with RW permissions, however, can still manually merge and push the patchset to the integration branch; Gitblit does not enforce vetoed patchsets on push. | |
| #### Reviews and Updated or Rewritten Patchsets | |
| If the patchset is updated or rewritten, all former review scores are ignored; review scores apply to specific revisions of patchsets - they are not blanket approvals/disapprovals. |