|
|
| (3 intermediate revisions by 2 users not shown) |
| Line 1: |
Line 1: |
| − | | + | #REDIRECT [[EMF Compare/Specifications/LogicalMergeCommandLine]] |
| − | == Part 2: general workflow and initial prototype ==
| + | |
| − | | + | |
| − | When a user wants to compare or merge EMF models from a command line, he needs to do that in an Eclipse environment similar to the one he used to create these models. As such, the environment requires some plugins to be installed but it may also requires some preferences to be set, some perspective to be activated etc.. Among these plugins, there are the mandatory ones that will be use to do the compare/merge operation: EMF Compare and EGit. Several options are possible to provision such an environment.
| + | |
| − | | + | |
| − | The first one is the ''manual'' way. It is necessary to download the Eclipse environment and install all the required plugins. Then, the git repository(-ies) that contains the models have to be cloned and binded to the Eclipse environment.. All these tasks have to be done manually, on each computer that wants to execute a comparison or a merge. Finally, it is necessary to write a program that allows to launch and manage the comparison/merge from the command line interface.
| + | |
| − | | + | |
| − | The second one is the ''programmatic'' way. All the tasks done manually in the first method have to be done programmatically on this one. That means we need to find a way to allow to the user to specify what he wants to provision in an Eclipse environment. It can be a very long and fastidious development that involves a lot of various APIs. The advantage of this method is there just to execute the final program on each computer that wants to execute a comparison or a merge, there is no further manual tasks.
| + | |
| − | | + | |
| − | [https://wiki.eclipse.org/Eclipse_Oomph_Installer Eclipse Oomph] is a technology that allows to provision a set of plugins in an Eclipse IDE, clone Git repositories, bind Git repositories to this IDE, checking out projects, setting workspace preferences... The configuration is model driven, with files called Oomph setup model files. As such, Oomph seems to be a good framework on top of which we could implement the compare and merge command line. We only have to call the Oomph APIs instead of call a lot and various APIs from a lot of technologies. | + | |
| − | We think the Eclipse Oomph technology is the most appropriate for this need in terms of costs, time, maintainability, reliability and performances.
| + | |
| − | | + | |
| − | === New shell commands ===
| + | |
| − | | + | |
| − | We will initially develop new shell scripts that will add new commands to git:
| + | |
| − | *git logicalmerge
| + | |
| − | *git logicaldiff
| + | |
| − | *git logicalmergetool
| + | |
| − | | + | |
| − | These scripts must be added on each computer that need to do logical git operations from command line interface, to enable them.
| + | |
| − | | + | |
| − | On linux systems, to create a new git command named logicalmerge, the script must be named git-logicalmerge.sh. Then, the scripts have to be reachable from your <code>PATH</code> and have execution permissions.
| + | |
| − | | + | |
| − | Basically, each command will mimic its ''non logical'' counterpart. They will take a additional mandatory parameter: an Eclipse Oomph setup model file describing the environment into which the compare/merge operation should be handled. In a first time, we will handle only a subset of standard parameters of counterpart commands.
| + | |
| − | | + | |
| − | ==== git logicalmerge ====
| + | |
| − | | + | |
| − | The ''logicalmerge'' command is the logical version of the git merge command. To see a full description of the git merge command, please visit [http://git-scm.com/docs/git-merge http://git-scm.com/docs/git-merge].
| + | |
| − | | + | |
| − | The command is specified as below:
| + | |
| − | | + | |
| − | <code>
| + | |
| − | git logicalmerge <setup> <commit>
| + | |
| − | </code>
| + | |
| − | | + | |
| − | Assume the following history exists and the current branch is ''master'':
| + | |
| − | | + | |
| − | <code>
| + | |
| − | A---B---C topic
| + | |
| − | /
| + | |
| − | D---E---F---G master
| + | |
| − | </code>
| + | |
| − | | + | |
| − | Then <code>git logicalmerge mySetupModel.setup topic</code> will replay the changes made on the ''topic'' branch since it diverged from ''master'' (i.e., ''E'') until its current commit (''C'') on top of ''master'', and record the result in a new commit along with the names of the two parent commits and a log message from the user describing the changes.
| + | |
| − | | + | |
| − | <code>
| + | |
| − | A---B---C topic
| + | |
| − | / \
| + | |
| − | D---E---F---G---H master
| + | |
| − | </code>
| + | |
| − | | + | |
| − | You can also replace the topic branch name by his commit id: <code>git logicalmerge mySetupModel.setup 87ad5ff</code>
| + | |
| − | | + | |
| − | ==== git logicaldiff ====
| + | |
| − | | + | |
| − | The ''logicaldiff'' command is the logical version of the git diff command. To see a full description of the git diff command, please visit [http://git-scm.com/docs/git-diff http://git-scm.com/docs/git-diff].
| + | |
| − | | + | |
| − | The command is specified as below:
| + | |
| − | | + | |
| − | <code>
| + | |
| − | git logicaldiff <setup> <commit> [<commit>] [–- <path>]
| + | |
| − | </code>
| + | |
| − | | + | |
| − | To see the changes between a revision and the HEAD revision, you should omit the second <code>commit</code>.
| + | |
| − | | + | |
| − | <code>
| + | |
| − | git logicaldiff <setup> <commit> [--] [<path>...]
| + | |
| − | </code>
| + | |
| − | | + | |
| − | In all cases, <code>[– <path>]</code> option allows to filter the diff command only on files that match the <code><path></code>.
| + | |
| − | | + | |
| − | In all cases, <code><commit></code> can refers to a branch name or a commit id.
| + | |
| − | | + | |
| − | ==== git logicalmergetool ====
| + | |
| − | | + | |
| − | The logicalmergetool command is the logical version of the git mergetool command. To see a full description of the git mergetool command, please visit [http://git-scm.com/docs/git-mergetool http://git-scm.com/docs/git-mergetool]. Here is the constructions allowing for the git logicalmergetool:
| + | |
| − | | + | |
| − | <code>
| + | |
| − | git logicalmergetool <setup>
| + | |
| − | </code>
| + | |
| − | | + | |
| − | Run logical merge conflict resolution tools to resolve logical merge conflicts. In our case, it means run Eclipse and call the EGit merge tool on file(s) in conflict(s).
| + | |
| − | | + | |
| − | === Workflow ===
| + | |
| − | | + | |
| − | Each shell script will wrapper of an Eclipse standalone application (provided by the EMF Compare project). This standalone application will itself call some Oomph API.
| + | |
| − | | + | |
| − | First, Oomph will provision an Eclipse with all appropriate plugins to launch the logical git operation. These plugins are EGit, EMF Compare and their dependencies. If the Oomph setup model provided as parameter contains other plugins (represented by the name of the repository and the name of the plugin/feature), they will be provisioned too.
| + | |
| − | | + | |
| − | For a given Oomph setup model file, the provisioning operation is executed only once. Indeed, if you launch again a git logical operation with the same Oomph setup model file, then the already provisioned Eclipse IDE corresponding to the setup model will be reused. It avoids to execute this potentially costly task each time.
| + | |
| − | | + | |
| − | In order to retrieve the Eclipse associated to a given Oomph setup model file, we will store all provisioned Eclipses in the temporary folder of the system. We will use a hash function on the Oomph setup model file to generate/retrieve a unique id. This unique id will be the name of the folder containing the provisioned Eclipse.
| + | |
| − | | + | |
| − | Then, in this provisioned Eclipse, the list of tasks contained in the Oomph setup model will be executed.
| + | |
| − | | + | |
| − | This Oomph setup model will contain, at least:
| + | |
| − | *The path where the workspace will be created.
| + | |
| − | *The git repository(-ies) to clone/bind with the Eclipse IDE.
| + | |
| − | *The project(s) (represented by his path on the computer) to import in the workspace associated with the Eclipse IDE.
| + | |
| − | | + | |
| − | Once all Oomph tasks executed, EMF Compare will call the logical git operation with the others parameters provided in the command line interface.
| + | |
| − | Once the git logical operation has been executed, the user can see the results in his command line tool.
| + | |
| − | | + | |
| − | If the result shows conflict(s) on involved model(s), the user will call the <code>git logicalmergetool</code> command. This command will launch a full-fledged Eclipse IDE (not a simple headless application) with a workspace containing these files. This full-fledged Eclipse IDE is the same as the one provisioned previously by Oomph. The user will have to manually launch EGit's merge tool on the files in conflict to solve the issues, and then manually close the Eclipse to properly finish the process.
| + | |
| − | | + | |
| − | As an axis of evolution, in case of conflict(s), when the full-fledged Eclipse IDE has been launched, the EGit's merge tool could be automatically launched on file(s) in conflict(s).
| + | |
| − | | + | |
| − | Here is a schema representing the workflow of the process for the logical merge command (the workflow is nearly the same for the logical diff):
| + | |
| − | | + | |
| − | (Gray steps done by the user, blue steps done automatically)
| + | |
| − | | + | |
| − | [[File:EMFCompare GitLogicalMerge Workflow.png | center]]
| + | |
| − | | + | |
| − | An initial prototype of such a workflow is available on the EMF Compare's gerrit: https://git.eclipse.org/r/#/c/29889/
| + | |
