Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | We use [[Git>>url:http://git-scm.com/||shape="rect"]] to manage our source code. Our [[Stash>>url:http://git.rtsys.informatik.uni-kiel.de/||shape="rect"]] installation is the front end we use to manage our different Git repositories. | ||
| 2 | |||
| 3 | This page will help you get started with Git and getting the KIELER sources. For more detailed information, see [[Git's official documentation>>url:http://git-scm.com/documentation||shape="rect"]]. The [[SVN Crash Course>>url:http://git-scm.com/course/svn.html||shape="rect"]] is probably a good place to start. For more in-depth information, see the [[Git Community Book>>url:http://book.git-scm.com/||shape="rect"]] or the [[Pro Git>>url:http://progit.org/book/||shape="rect"]] book. Furthermore, each office has a copy of another excellent book about Git, so you might as well go ahead and read it. This will help ease you in to some of the more advanced concepts of Git, which are a little hard to understand at first. If everything else fails, Miro and Tim will be more than happy to help you with Git and rant about how excellent of a system it is. For more information on Git Eclipse integration, see the [[EGit User's Guide>>url:http://wiki.eclipse.org/EGit/User_Guide||shape="rect"]]. | ||
| 4 | |||
| 5 | **Content** | ||
| 6 | |||
| 7 | |||
| 8 | |||
| 9 | {{toc/}} | ||
| 10 | |||
| 11 | = Checking Out KIELER = | ||
| 12 | |||
| 13 | KIELER is essentially a large heap of Eclipse plug-ins that aren't easy to find your way through as a new developer. The [[doc:Overview]] page has a nice overview of our sub-projects and what plug-ins belong where. This section will tell you how to get the KIELER sources. As for what plug-ins you will actually need to checkout, ask your advisor. | ||
| 14 | |||
| 15 | {{info title="Important Hint for Users Behind Firewalls"}} | ||
| 16 | Repository access via SSH runs on port 7999. For accessing the repositories in read-only mode, HTTP transfer is also possible, but not recommended. | ||
| 17 | {{/info}} | ||
| 18 | |||
| 19 | Checkout of the Git repository is possible either using the SSH or the HTTP protocol. We strongly recommend using SSH; if you still want to use HTTP, omit the SSH key creation and upload in the instructions below. | ||
| 20 | |||
| 21 | 1. If you don't have an SSH key yet, you have to create one. You can do this by:\\ | ||
| 22 | 1*. Creating one using the command {{code language="none"}}ssh-keygen{{/code}} on the command line. Simply type {{code language="none"}}ssh-keygen{{/code}}, confirm the default destination file ~~/.ssh/id_rsa, and choose whether to give a passphrase. If you have a passphrase, you need to enter it whenever you use your SSH key for the first time in a session. You can omit the passphrase, but that makes the key less secure. As result, the tool generates a private key ~~/.ssh/id_rsa, which has to be kept secret, and a public key ~~/.ssh/id_rsa.pub. | ||
| 23 | 1*. Using Eclipse to generate it. You can find this function under //Preferences - General - Network Connections - SSH2 - Key Management//. | ||
| 24 | 1. Register with [[Stash>>url:http://git.rtsys.informatik.uni-kiel.de||shape="rect"]] and upload your public SSH key (//Profile - SSH Keys - Add Key//). | ||
| 25 | 1. Copy one of the following repository URIs into the clipboard: {{code language="none"}}ssh://git@git.rtsys.informatik.uni-kiel.de:7999/KIELER/the_repo_to_clone.git{{/code}} where {{code language="none"}}the_repo_to_clone{{/code}} is either {{code language="none"}}pragmatics{{/code}} or {{code language="none"}}semantics{{/code}} (if in doubt, ask your adviser which of these you need). If you for whatever reason insist on using the less efficient HTTP protocol, use the following URI: (% class="nolink" %)http:~/~/youraccountname@git.rtsys.informatik.uni-kiel.de/scm/KIELER/the_repo_to_clone.git{{code language="none"}}{{/code}}(%%)) | ||
| 26 | 1. Open the //Git Repositories// view, right-click it, select //Paste Repository Path or URI//, select //ssh// connection protocol, //Next//, select master branch, //Next//, select destination directory (e.g. /home/<username>/shared/kieler), //Finish//. Wait for the repository to be downloaded to your computer. Note that the whole history of the repository will be stored in your local filesystem, which is pretty awesome. | ||
| 27 | 1. Right-click the //Working directory// entry in the //kieler// repository, select //Import Projects//, //Next//, select the projects that you want in your workspace, //Finish.// | ||
| 28 | |||
| 29 | Checking out on the command line is done with the command {{code language="none"}}git clone <URI> <local path>{{/code}}. Instead of the URI you can also use a path to a local repository, which then creates a clone of that repository. | ||
| 30 | |||
| 31 | == Adding an Existing Local Repository to EGit == | ||
| 32 | |||
| 33 | If you have already cloned the KIELER repository and are only looking for a way to import it into EGit, follow these steps: | ||
| 34 | |||
| 35 | 1. Click the button //Add an existing local Git Repository to this view// in the //Git Repositories// view and enter the local path. | ||
| 36 | 1. Import the plugin projects that you need.\\ | ||
| 37 | |||
| 38 | == Importing Plugins to the Eclipse Workspace == | ||
| 39 | |||
| 40 | In the Git Repository View, perform **Right-click > Import Projects...** on the //Working directory// or //Plugins// folder. Hit //Next//. In the following dialog you can //Deselect all// and afterwards select the plugins that you need for your developing task. | ||
| 41 | |||
| 42 | [[image:attach:git_repo_browser_import_plugins.png]] | ||
| 43 | |||
| 44 | For example, if you want to start **KIELER with SCCharts** you need to import | ||
| 45 | |||
| 46 | 1. ((( | ||
| 47 | **all core plugins** (core.*) from the semantics and pragmatics repositories | ||
| 48 | ))) | ||
| 49 | 1. **all SCCharts plugins** (sccharts.*) from the semantics repository, **unless sccharts.prio.dependencies**,** sccharts.prio.dependencies.klighd**, **sccharts.prio.s**,** sccharts.prio.sim.s** | ||
| 50 | 1. **all required plugins** for the already imported ones | ||
| 51 | |||
| 52 | As a result you will have the following plugin projects in your workspace: | ||
| 53 | |||
| 54 | 1. **From** the **pragmatics repo**: core, core.kgraph, core.kgraph.text, core.kgraph.text.ui, core.kivi, core.krendering, core.krendering.extensions, core.ui, kiml, kiml.formats, kiml.graphviz.dot, kiml.graphviz.layouter, kiml.service, kiml.ui, klay.layered, klighd, klighd.piccolo, klighd.ui, edu.umd.cs.piccolo | ||
| 55 | 1. **From** the **semantics repo**: core.annotations, core.annotations.edit, core.annotations.text, core.annotations.text.ui, core.kexpressions, core.kexpressions.edit, core.kexpressions.keffects, core.kexpressions.keffects.edit, core.kexpressions.keffects.ui, core.kexpressions.text, core.kexpressions.text.ui, core.kexpressions.ui, core.model, core.perspectives, core.product, kex, kex.ui, kico, kico.klighd, kico.ui, kitt, kitt.klighd, klay.layered, klighd, klighd.piccolo, klighd.ui, prom, s, s.sc, s.sim, s.sim.kivi, s.sim.sc, s.sim.sj, s.sj, s.ui, sc, sccharts, sccharts.edit, sccharts.editor, sccharts.eso, sccharts.kivi, sccharts.klighd, sccharts.prom, sccharts.s, sccharts.scg, sccharts.sim.c, sccharts.sim.s, sccharts.text, sccharts.text.ui, scg, scg.s, scl, sim.benchmark, sim.instructions, sim.kiem, sim.kiem.config, sim.kiem.ui.datacomponent, sim.kivi, sim.signals, sjl, org.freemarker, org.json | ||
| 56 | |||
| 57 | === Troubleshooting / Resolving Plugin Dependencies === | ||
| 58 | |||
| 59 | If there are errors in your workspace, they are most likely the result of missing plugins. To solve this, check if the MANIFEST.MF file of the project has error markers. **Import missing plugin dependencies** if required. | ||
| 60 | |||
| 61 | [[image:attach:resolve_missing_plugins.png]] | ||
| 62 | |||
| 63 | After all dependencies are solved and there are still errors, you should clean your workspace via **Project > Clean > All projects**. | ||
| 64 | |||
| 65 | If there are errors in an xtend-gen folder you can delete this folder so that the contents are re-compiled. (It sometimes happens that this folder is not deleted as part of the clean.) | ||
| 66 | |||
| 67 | There should not be any errors after all required plugins are imported and compiled correctly. | ||
| 68 | |||
| 69 | = Updating the Repository = | ||
| 70 | |||
| 71 | Your working copy must be clean before you can merge any updates into it. Therefore, always commit your changes locally before you pull. If you don't want to commit them into the master branch, commit them into a new branch. Note that pulling is the same as fetching remote changes and merging them into your local branch. Since a normal merge operation is involved, this can lead to conflicts, which need to be resolved as described below. Note that pulling always merges the remote changes into your current branch. If that's not what you want, checkout the correct branch first or just do a //fetch//. | ||
| 72 | |||
| 73 | Do one of the following three things: | ||
| 74 | |||
| 75 | * Right-click one of the KIELER projects, then from the //Team// submenu choose //Pull//. | ||
| 76 | * Right-click the KIELER repository in the //Git Repositories// view and click //Pull//. | ||
| 77 | * Enter {{code language="none"}}git pull{{/code}} on the command line and refresh your workspace. | ||
| 78 | |||
| 79 | = Resolving Conflicts = | ||
| 80 | |||
| 81 | Whenever branches are merged or rebased, conflicts can occur. They can be resolved by adjusting the state of your working copy, marking it as clean, and committing the changes. Conflicted files are modified so they contain both your version and the remote version. Edit them until all conflict areas are clean. In Eclipse this can be done by right-clicking the conflicted files - //Team - Merge Tool//. | ||
| 82 | |||
| 83 | {{warning}} | ||
| 84 | If you try to pull from a remote repository or merge branches although you have local uncommitted changes, and the merge would affect the same files, Git leaves those files as they are, thus discarding the changes that would be made by the pull or merge operation. As a consequence, committing such a conflicted state would ignore the changes of the merged branch even if the commit graph looks like a regular merge has happened. Therefore keep in mind never to pull or merge with uncommitted changes. | ||
| 85 | {{/warning}} | ||
| 86 | |||
| 87 | **Taking your version of conflicted files:** {{code language="none"}}git checkout --ours <path>{{/code}} | ||
| 88 | |||
| 89 | **Taking the remote version of conflicted files:** {{code language="none"}}git checkout --theirs <path>{{/code}} | ||
| 90 | |||
| 91 | = Committing Changes = | ||
| 92 | |||
| 93 | Git manages changes in two separate steps: | ||
| 94 | |||
| 95 | 1. Commit changes to your local repository. | ||
| 96 | 1. Push the commit to the remote repository. | ||
| 97 | |||
| 98 | The first step can be done offline, which is very useful in situations where you don't have an internet connection, but would like to save intermediate development snapshots in the history. You can push multiple commits to the remote repository, which for example means that if you are performing changes that would create broken intermediate states, you can commit any number of snapshots locally and only push the whole bundle of commits after you have reached a state that works again. | ||
| 99 | |||
| 100 | If another developer has pushed changes since the last time you have pulled from the server, your attempt to push your commits online may fail. In this case you need to pull the remote changes before you can push. Never use force pushing! ({{code language="none"}}git push -f{{/code}}) | ||
| 101 | |||
| 102 | {{info title="Before you commit anything..."}} | ||
| 103 | Make sure you have set up your name and email address properly, as described on the [[doc:Configuring Eclipse]] page. | ||
| 104 | {{/info}} | ||
| 105 | |||
| 106 | == Committing == | ||
| 107 | |||
| 108 | To commit changes with EGit, do one of the following and select the files you would like to commit: | ||
| 109 | |||
| 110 | * Right-click one of the KIELER projects, and from the //Team// submenu, choose //Commit//. | ||
| 111 | * Right-click the KIELER repository in the //Git Repositories// view and choose //Commit//. | ||
| 112 | |||
| 113 | To commit your changes on the command line, do the following: | ||
| 114 | |||
| 115 | 1. Use {{code language="none"}}git add{{/code}} to select (//stage//) the files you would like to commit (new files as well as modified files). | ||
| 116 | 1. Enter {{code language="none"}}git commit{{/code}} to create a commit from the staged files. | ||
| 117 | |||
| 118 | == Pushing == | ||
| 119 | |||
| 120 | To push your commits to a remote repository with EGit, do one of the following: | ||
| 121 | |||
| 122 | * Right-click one of the KIELER projects, and from the //Team// submenu, choose //Push to Upstream//. | ||
| 123 | * Right-click the KIELER repository in the //Git Repositories// view and choose //Push to Upstream//. | ||
| 124 | |||
| 125 | To push your commits on the command line, enter {{code language="none"}}git push{{/code}}. | ||
| 126 | |||
| 127 | = Getting Earlier Versions of Files = | ||
| 128 | |||
| 129 | If you want to revert //all// your local changes and get back to the previous repository state, use {{code language="none"}}git reset --hard{{/code}} or the //Reset// item in the EGit context menu. If you only want to revert some specific files, do one of the following: | ||
| 130 | |||
| 131 | * Right click the files, click //Replace With//, click //HEAD Revision//. | ||
| 132 | * Enter {{code language="none"}}git checkout <path>{{/code}} on the command line. | ||
| 133 | |||
| 134 | By giving a branch, tag, or commit number in {{code language="none"}}git checkout <commit> <path>{{/code}}, you can get to any existing version of the files. If no path is given, {{code language="none"}}git checkout <commit>{{/code}} switches your whole working copy and index to the specified branch, tag, or commit number. If {{code language="none"}}git reset{{/code}} is given a commit number, the current branch is modified to point at the given commit. | ||
| 135 | |||
| 136 | {{warning}} | ||
| 137 | This is a brute force modification, and you probably won't be able to push the new branch | ||
| 138 | {{/warning}} | ||
| 139 | |||
| 140 | = Cleaning Your Working Directory = | ||
| 141 | |||
| 142 | In case the working directory is messed up with unstaged files, which are not affected by {{code language="none"}}git reset --hard{{/code}}, a clean up is achieved by means of {{code language="none"}}git clean -f{{/code}}. The additional switch {{code language="none"}}-d{{/code}} applies this to directories, respectively. Hence, {{code language="none"}}git reset{{/code}} followed by {{code language="none"}}git clean{{/code}} act like {{code language="none"}}svn revert{{/code}}. | ||
| 143 | |||
| 144 | {{code language="none"}}git clean -X{{/code}} removes only the files that are ignored by Git, that is mainly the .class files generated by the Java compiler. A full rebuild is required afterwards. | ||
| 145 | |||
| 146 | = Branching and Merging = | ||
| 147 | |||
| 148 | Branches are used to structure your development and are an essential tool for effective work in the KIELER team. Read the [[doc:Source Code Management]] page if you haven't yet understood what branches are good for. | ||
| 149 | |||
| 150 | == Creating a Branch == | ||
| 151 | |||
| 152 | Do one of the following: | ||
| 153 | |||
| 154 | * Right-click the KIELER repository in the //Git Repositories// view, click //Switch To//, click //New Branch//. | ||
| 155 | * On the command line, enter {{code language="none"}}git branch <name>{{/code}}. In this case, the new branch is not active; if you want to activate the new branch while creating it, enter {{code language="none"}}git checkout -b <name>{{/code}}. | ||
| 156 | |||
| 157 | In either case the new branch starts at the current position of your working copy, i.e. it branches from the current branch you are on. In order to branch from a different position, either check out that other branch first or select it as //source ref// in the EGit wizard (on the command line simply type git branch <name> <start_point>). | ||
| 158 | |||
| 159 | == Switching to Another Branch == | ||
| 160 | |||
| 161 | Do one of the following: | ||
| 162 | |||
| 163 | * Navigate to the branch in the KIELER repository in the //Git Repositories// view, right click it, click //Checkout//. | ||
| 164 | * On the command-line, enter {{code language="none"}}git checkout <name>{{/code}}. | ||
| 165 | |||
| 166 | Note that your local uncommitted changes are transferred when switching the current branch. | ||
| 167 | |||
| 168 | == Merging Branches == | ||
| 169 | |||
| 170 | You always merge another branch into the current branch. Therefore you first have to checkout the target branch prior to merging. Then, do one of the following: | ||
| 171 | |||
| 172 | * Navigate to the source branch in the //Git Repositories// view, right-click it, click //Merge.// | ||
| 173 | * On the command line, enter {{code language="none"}}git merge <source_name>{{/code}}. | ||
| 174 | |||
| 175 | This creates a new //merge commit//, i.e. a commit with two source commits, and the target branch (the one you're currently on) contains all changes that have been done in the source branch (the one selected for merge). The source branch is not modified. A merge is done implicitly when pulling: assuming you're on branch master, the command git pull origin master is the same as git fetch origin followed by git merge origin/master, where origin/master is the remote tracking branch for master. | ||
| 176 | |||
| 177 | = Working With Multiple Remote Repositories = | ||
| 178 | |||
| 179 | Stash allows the creation of personal server-side clones of the KIELER repository, which is highly encouraged as described on the [[doc:Source Code Management]] page. When working with such clones, it is often necessary to synchronize the different server-side repositories with the local one. Git supports this by allowing to configure multiple //remotes// in the local repository. On the command line this is done simply by entering git remote add <name> <url>, where <name> is an arbitrary local identifier for the remote repository. For example, a remote named origin is automatically created when a local repository clone is created through git clone <url>. | ||
| 180 | |||
| 181 | When you push or pull branches, simply select the remote you wish to interfere with. Pulling is done by {{code language="none"}}git pull <remote> <branch>{{/code}}, and pushing is done by {{code language="none"}}git push <remote> <branch>{{/code}}. |