| <?xml version="1.0" encoding="ISO-8859-1"?> | |
| <!-- | |
| Licensed to the Apache Software Foundation (ASF) under one | |
| or more contributor license agreements. See the NOTICE file | |
| distributed with this work for additional information | |
| regarding copyright ownership. The ASF licenses this file | |
| to you under the Apache License, Version 2.0 (the | |
| "License"); you may not use this file except in compliance | |
| with the License. You may obtain a copy of the License at | |
| https://www.apache.org/licenses/LICENSE-2.0 | |
| Unless required by applicable law or agreed to in writing, | |
| software distributed under the License is distributed on an | |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY | |
| KIND, either express or implied. See the License for the | |
| specific language governing permissions and limitations | |
| under the License. | |
| --> | |
| <document> | |
| <properties> | |
| <title>Git notes</title> | |
| <author email="dev@uima.apache.org"> Apache UIMA Documentation Team</author> | |
| </properties> | |
| <body> | |
| <section name="Configuring some aspects of Git Repo"> | |
| <p>You may create a special file in a branch, at the top level, named | |
| <code>.asf.yaml</code> which controls some automation at Apache.</p> | |
| <p>For some settings, this file must be in the "master" branch.</p> | |
| <p>See <a target="_blank" rel="nofollow noopener" | |
| href="https://cwiki.apache.org/confluence/display/INFRA/.asf.yaml+features+for+git+repositories">this page</a> | |
| for details.</p> | |
| </section> | |
| <section name="Frequently used git actions"> | |
| <h2>Working with two branches in one repo</h2> | |
| <p>It may be best to have two separate local directories, each with a separate clone. | |
| because if you just have one clone and switch between branches, the switch operation | |
| the working tree might have "extra files" from the other branch, which you'll need to be | |
| careful to ignore. In Eclipse these extra folders will look like they're waiting to be added.</p> | |
| <p>To clone and then check-out a non-default branch, use | |
| <pre>git clone https://... -b branch-name</pre></p> | |
| <h3>Alternative: Have one clone, switch between branches</h3> | |
| <p>For example, if you have both master, and master-v2 (as is the case for core uima). | |
| </p> | |
| <table class="downloads"> | |
| <tr> | |
| <th>Goal / Task</th> | |
| <th>Git command</th> | |
| <th>Comments</th> | |
| </tr> | |
| <tr> | |
| <td>Switch between branches</td> | |
| <td><p>git status (to confirm things are clean)</p> | |
| <p>git checkout <branch-name></p> | |
| </td> | |
| <td><p>The checkout switches to the other branch. Before you do this, please insure the working tree | |
| has no local modifications. Otherwise the checkout command will complain. | |
| </p> | |
| <p>The checkout operation may not remove directories or files that are present in one branch but not in the other. | |
| Don't remove these (Eclipse gets confused if you remove them); just don't stage them or otherwise change them. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td>Create new branches for bug-fixing or features</td> | |
| <td>see below, but do for each version</td> | |
| <td>This is if you are independently committing changes to each branch</td> | |
| </tr> | |
| </table> | |
| <h2>Common situations</h2> | |
| <table class="downloads"> | |
| <tr> | |
| <th>Goal / Task</th> | |
| <th>Git command</th> | |
| <th>Comments</th> | |
| </tr> | |
| <tr> | |
| <td>Creating a new branch for a feature or Jira issue</td> | |
| <td><p>git clone https:... -b master-v2</p> | |
| <p>git checkout -t -b new-branch-name</p> | |
| <p>git push -u origin new-branch-name</p> | |
| <p><b>OR</b></p> | |
| <p>create the branch on the github.com website, from the desired master (e.g. use</p> | |
| the github pulldowns to switch the branch first to the one to branch from, | |
| e.g. "master-v2"). | |
| <p>git checkout -b new-branch-name</p> | |
| <p>(no push is needed, the remote already has the new branch)</p> | |
| </td> | |
| <td><p>The first operation sets the base from which you will branch. | |
| If no <code>-b branch-name</code> is specified, the default branch is used (typically master).</p> | |
| <p>The checkout with -b will create a new branch and switch to it. The -t will | |
| sets up the configuration so that <code>git pull</code> (with no arguments) will | |
| pull from the starting branch (in this example, the local master-v2). | |
| </p> | |
| <p>The push will update the remote with the new branch. The -u operation creates the remote tracking branch, | |
| so that <code>git push</code> will go to the corresponding new remote for this new branch. | |
| </p> | |
| </td> | |
| </tr> | |
| <tr> | |
| <td>Undo some commits</td> | |
| <td><p>git log --oneline</p> | |
| <p>git reset --hard the-hash-or-ref</p> | |
| <p>or</p> | |
| <p>git revert the-hash-or-ref</p> | |
| </td> | |
| <td><p>The log command shows you the hashes for the commits, so you can find the last one you want preserved.</p> | |
| <p>The reset should only be used if this is a local commit and hasn't been pushed.</p> | |
| <p>The revert applies the changes needed to revert. Use it when the commit has been pushed to some public spot.</p> | |
| <p> </p> | |
| <p>If the remote as been updated, use "revert" and push the change to the remote.</p> | |
| </td> | |
| </tr> | |
| </table> | |
| </section> | |
| </body> | |
| </document> |