|
1 | | -# pk-vcs-git |
| 1 | +# Overview |
| 2 | +Pk-vcs-git is lightweight library for execute basic Git VCS operations (merge, branch create etc). It uses [pk-vcs-api](https://github.com/ProjectKaiser/pk-vcs-api) exposing IVCS implementation for Git repositories and [JGit](https://eclipse.org/jgit/) as framework to work with Git repositories |
| 3 | + |
| 4 | +# Terms |
| 5 | +- Workspace Home |
| 6 | + - Home folder of all folders used by vcs-related operations. See [pk-vcs-api](https://github.com/ProjectKaiser/pk-vcs-api) for details |
| 7 | +- Repository Workspace |
| 8 | + - Folder for LWC folders related to Repository of one type. See [pk-vcs-api](https://github.com/ProjectKaiser/pk-vcs-api) for details |
| 9 | +- Locked Working Copy, LWC |
| 10 | + - Folder where vcs-related operations are executed. Provides thread- and process-safe repository of working folders. See [pk-vcs-api](https://github.com/ProjectKaiser/pk-vcs-api) for details |
| 11 | +- Test Repository |
| 12 | + - Git repository which is used to execute functional tests |
| 13 | + - Hosted on [Github](https://github.com/) using username and password provided by enviroment variables (see below) |
| 14 | + - Generates new before and deletes after each test |
| 15 | + - Named randomly (uuid is used) |
| 16 | + - [Kohsuke Github API](http://github-api.kohsuke.org/) is used as to work with Github API |
| 17 | + |
| 18 | +# Using pk-vcs-git |
| 19 | +- Add github-hosted pk-vcs-git project as maven dependency using [jitpack.io](https://jitpack.io/). As an example, add following to gradle.build file: |
| 20 | + ```gradle |
| 21 | + allprojects { |
| 22 | + repositories { |
| 23 | + maven { url "https://jitpack.io" } |
| 24 | + } |
| 25 | + } |
| 26 | + |
| 27 | + dependencies { |
| 28 | + compile 'com.github.ProjectKaiser:pk-vcs-git:master-SNAPSHOT' |
| 29 | + } |
| 30 | + ``` |
| 31 | +- Create Workspace Home instance providing path to any folder as Workspace Home folder path. This folder will contain repositories folders (if different vcs or repositories are used) |
| 32 | +```java |
| 33 | + public static final String WORKSPACE_DIR = System.getProperty("java.io.tmpdir") + "git-workspaces"; |
| 34 | + ... |
| 35 | + IVCSWorkspace workspace = new VCSWorkspace(WORKSPACE_DIR); |
| 36 | + ... |
| 37 | +``` |
| 38 | +- Obtain Repository Workspace from Workspace Home providing a certain Repository's url. The obtained Repository Workspace will represent a folder within Workspace Home dir which will contain all Working Copies relating to the provided VCS Repository |
| 39 | +```java |
| 40 | + String repoUrl = "https://github.com/ProjectKaiser/pk-vcs-api"; |
| 41 | + IVCSRepositoryWorkspace repoWorkspace = workspace.getVCSRepositoryWorkspace(repoUrl); |
| 42 | +``` |
| 43 | +- Create `GitVCS` instance providing Repository Workspace |
| 44 | +```java |
| 45 | + IVCS vcs = new GitVCS(repoWorkspace); |
| 46 | +``` |
| 47 | +- Use methods of `IVCS` interface. See [pk-vcs-api](https://github.com/ProjectKaiser/pk-vcs-api) for details |
| 48 | +- Use `vcs.setProxy()` and `vcs.setCredentials()` if neccessary |
| 49 | + |
| 50 | +# Implementation details |
| 51 | +- [JGit](https://eclipse.org/jgit/) is used as framework to work with Git repositories |
| 52 | +- [Github](https://github.com/) is used as hosting of a Test Repository |
| 53 | +- LWC is obtained for each vcs operation. |
| 54 | +- `getLocalGit(IVCSLockedWorkingCopy wc)` method is used to create a Git implementation to execute vcs operations within `wc` Working Copy |
| 55 | + - If provided LWC is empty then current Test Repository is cloned into this LWC, otherwise just Git object is created |
| 56 | +- If `IVCS.setProxy()` is called then provided proxy is used to each url which contains `repoUrl` |
| 57 | + |
| 58 | +# Functional testing |
| 59 | +- Github is used for hosting the Test Repository |
| 60 | + - [Kohsuke Github API](http://github-api.kohsuke.org/) is used to create and delete Test Repository |
| 61 | + - `PK_VCS_TEST_GITHUB_USER` enviroment var or JVM var is used as username for access to Github |
| 62 | + - `PK_VCS_TEST_GITHUB_PASS` enviroment var or JVM var is used as user password for access to Github |
| 63 | + - New Test Repository is created before each test and deletes automatically after each test |
| 64 | +- To execute tests just run GitVCSTest class as JUnit test. Tests from VCSAbstractTest class will be executed. See [pk-vcs-test](https://github.com/ProjectKaiser/pk-vcs-test) for details |
| 65 | +- NOTE: Github has some latency for exposing results of previosly executed operations. For example if create a new branch and immediately check branches list then Github could return old branches list. Need to wait a couple of second to get new list. So if a test failed then try to execute it again. |
| 66 | + |
| 67 | +# Limitations |
| 68 | +- Commit messages can not be atached to branch create and delete operations because Git does not exposes these operations as separate commits |
0 commit comments