|
1 | | -[](https://jitpack.io/#ProjectKaiser/scm4j-vcs-git) |
2 | | - |
3 | | -# Overview |
4 | | -scm4j-vcs-git is lightweight library for execute basic Git VCS operations (merge, branch create etc). It uses [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) exposing IVCS implementation for Git repositories and [JGit](https://eclipse.org/jgit/) as framework to work with Git repositories. |
5 | | -Features: |
6 | | -- Branch create and remove |
7 | | -- Branch merge with result return (success or list of conflicted files) |
8 | | -- Branch commits messages list |
9 | | -- Summarized diff between branches |
10 | | -- Branches list |
11 | | -- File content getting and setting |
12 | | -- File create and remove |
13 | | - |
14 | | -# Terms |
15 | | -- Workspace Home |
16 | | - - Home local folder of all folders used by vcs-related operations. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
17 | | -- Repository Workspace |
18 | | - - Local folder for LWC folders related to Repository of one type. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
19 | | -- Locked Working Copy, LWC |
20 | | - - Local folder where vcs-related operations are executed. Provides thread- and process-safe repository of working folders. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
21 | | -- Test Repository |
22 | | - - Git repository which is used to execute functional tests |
23 | | - - File-based repository is used |
24 | | - - Generates new one before and deletes after each test |
25 | | - - Named randomly (uuid is used) |
26 | | - |
27 | | -# Using scm4j-vcs-git |
28 | | -- Add github-hosted scm4j-vcs-git and scm4j-vcs-api projects as maven dependencies using [jitpack.io](https://jitpack.io/). As an example, add following to gradle.build file: |
29 | | - ```gradle |
30 | | - allprojects { |
31 | | - repositories { |
32 | | - maven { url "https://jitpack.io" } |
33 | | - } |
34 | | - } |
35 | | - |
36 | | - dependencies { |
37 | | - // versioning: master-SNAPSHOT (lastest build, unstable), + (lastest release, stable) or certain version (e.g. 1.1) |
38 | | - compile 'com.github.ProjectKaiser:scm4j-vcs-git:+' |
39 | | - } |
40 | | - ``` |
41 | | - Or download release jars from https://github.com/ProjectKaiser/scm4j-vcs-git/releases |
42 | | -- 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) |
43 | | -```java |
44 | | - public static final String WORKSPACE_DIR = System.getProperty("java.io.tmpdir") + "git-workspaces"; |
45 | | - ... |
46 | | - IVCSWorkspace workspace = new VCSWorkspace(WORKSPACE_DIR); |
47 | | - ... |
48 | | -``` |
49 | | -- 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 |
50 | | -```java |
51 | | - String repoUrl = "https://github.com/ProjectKaiser/scm4j-vcs-api"; |
52 | | - IVCSRepositoryWorkspace repoWorkspace = workspace.getVCSRepositoryWorkspace(repoUrl); |
53 | | -``` |
54 | | -- Create `GitVCS` instance providing Repository Workspace |
55 | | -```java |
56 | | - IVCS vcs = new GitVCS(repoWorkspace); |
57 | | -``` |
58 | | -- Use methods of `IVCS` interface. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
59 | | -- Use `vcs.setProxy()` and `vcs.setCredentials()` if necessary |
60 | | - |
61 | | -# Implementation details |
62 | | -- [JGit](https://eclipse.org/jgit/) is used as framework to work with Git repositories |
63 | | -- Each vcs operation is executed within a LWC |
64 | | -- `getLocalGit(IVCSLockedWorkingCopy wc)` method is used to create a Git implementation to execute vcs operations within `wc` Working Copy |
65 | | - - If provided LWC is empty then current Test Repository is cloned into this LWC, otherwise existing repository is just switched to required branch |
66 | | -- If `IVCS.setProxy()` is called then provided proxy is used for each url which contains `repoUrl` |
67 | | - |
68 | | -# Functional testing |
69 | | -- New local file-based Test Repository is created before each test and deletes automatically after each test |
70 | | -- To execute tests just run GitVCSTest class as JUnit test. Tests from VCSAbstractTest class will be executed. See [scm4j-vcs-test](https://github.com/ProjectKaiser/scm4j-vcs-test) for details |
71 | | -- Run `gradle test` to execute tests |
72 | | - |
73 | | -# Limitations |
74 | | -- Commit messages can not be attached to branch create and delete operations because Git does not exposes these operations as separate commits |
| 1 | +[](https://jitpack.io/#ProjectKaiser/scm4j-vcs-git) |
| 2 | + |
| 3 | +# Overview |
| 4 | +scm4j-vcs-git is lightweight library for execute basic Git VCS operations (merge, branch create etc). It uses [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) exposing IVCS implementation for Git repositories and [JGit](https://eclipse.org/jgit/) as framework to work with Git repositories. |
| 5 | +Features: |
| 6 | +- Branch create and remove |
| 7 | +- Branch merge with result return (success or list of conflicted files) |
| 8 | +- Branch commits messages list |
| 9 | +- Summarized diff between branches |
| 10 | +- Branches list |
| 11 | +- File content getting and setting |
| 12 | +- File create and remove |
| 13 | + |
| 14 | +# Terms |
| 15 | +- Workspace Home |
| 16 | + - Home local folder of all folders used by vcs-related operations. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
| 17 | +- Repository Workspace |
| 18 | + - Local folder for LWC folders related to Repository of one type. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
| 19 | +- Locked Working Copy, LWC |
| 20 | + - Local folder where vcs-related operations are executed. Provides thread- and process-safe repository of working folders. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
| 21 | +- Test Repository |
| 22 | + - Git repository which is used to execute functional tests |
| 23 | + - File-based repository is used |
| 24 | + - Generates new one before and deletes after each test |
| 25 | + - Named randomly (uuid is used) |
| 26 | + |
| 27 | +# Using scm4j-vcs-git |
| 28 | +- Add github-hosted scm4j-vcs-git project as maven dependency using [jitpack.io](https://jitpack.io/). As an example, add following to gradle.build file: |
| 29 | + ```gradle |
| 30 | + allprojects { |
| 31 | + repositories { |
| 32 | + maven { url "https://jitpack.io" } |
| 33 | + } |
| 34 | + } |
| 35 | + |
| 36 | + dependencies { |
| 37 | + // versioning: master-SNAPSHOT (lastest build, unstable), + (lastest release, stable) or certain version (e.g. 1.1) |
| 38 | + compile 'com.github.ProjectKaiser:scm4j-vcs-git:+' |
| 39 | + } |
| 40 | + ``` |
| 41 | + Or download release jars from https://github.com/ProjectKaiser/scm4j-vcs-git/releases |
| 42 | +- 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) |
| 43 | +```java |
| 44 | + public static final String WORKSPACE_DIR = System.getProperty("java.io.tmpdir") + "git-workspaces"; |
| 45 | + ... |
| 46 | + IVCSWorkspace workspace = new VCSWorkspace(WORKSPACE_DIR); |
| 47 | + ... |
| 48 | +``` |
| 49 | +- 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 |
| 50 | +```java |
| 51 | + String repoUrl = "https://github.com/MyUser/MyRepo"; |
| 52 | + IVCSRepositoryWorkspace repoWorkspace = workspace.getVCSRepositoryWorkspace(repoUrl); |
| 53 | +``` |
| 54 | +- Create `GitVCS` instance providing Repository Workspace |
| 55 | +```java |
| 56 | + IVCS vcs = new GitVCS(repoWorkspace); |
| 57 | +``` |
| 58 | +- Use methods of `IVCS` interface. See [scm4j-vcs-api](https://github.com/ProjectKaiser/scm4j-vcs-api) for details |
| 59 | +- Use `vcs.setProxy()` and `vcs.setCredentials()` if necessary |
| 60 | + |
| 61 | +# Implementation details |
| 62 | +- [JGit](https://eclipse.org/jgit/) is used as framework to work with Git repositories |
| 63 | +- Each vcs operation is executed within a LWC |
| 64 | +- `getLocalGit(IVCSLockedWorkingCopy wc)` method is used to create a Git implementation to execute vcs operations within `wc` Working Copy |
| 65 | + - If provided LWC is empty then current Test Repository is cloned into this LWC, otherwise existing repository is just switched to required branch |
| 66 | +- If `IVCS.setProxy()` is called then provided proxy is used for each url which contains `repoUrl` |
| 67 | + |
| 68 | +# Functional testing |
| 69 | +- New local file-based Test Repository is created before each test and deletes automatically after each test |
| 70 | +- To execute tests just run GitVCSTest class as JUnit test. Tests from VCSAbstractTest class will be executed. See [scm4j-vcs-test](https://github.com/ProjectKaiser/scm4j-vcs-test) for details |
| 71 | +- Run `gradle test` to execute tests |
| 72 | + |
| 73 | +# Limitations |
| 74 | +- Commit messages can not be attached to branch create and delete operations because Git does not exposes these operations as separate commits |
0 commit comments