### Clone Repository Example

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows a basic example of cloning a Git repository using the Repository Service. Ensure the repository URL and target path are correctly specified.

```ABAP
DATA(\(lr_repo_service) = cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )

cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )->clone(
  url = 'https://github.com/abapGit/abapGit.git'
  path = '/path/to/local/repo'
)
```

--------------------------------

### General Documentation Entry Points

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

This section guides users on where to start for an overview and complete navigation of the abapgit ADT Frontend documentation.

```APIDOC
## General Documentation Entry Points

To get started with the abapgit ADT Frontend documentation:

1. Read `README.md` for an overview.
2. Read `INDEX.md` for complete navigation.
```

--------------------------------

### Progress Monitor Lifecycle Example

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates the lifecycle of an IProgressMonitor, including starting, reporting progress, checking for cancellation, and completing the task. Ensure to always call monitor.done() in a finally block.

```java
IProgressMonitor monitor = ...;

// Start task
monitor.beginTask("Loading repository", 100);

try {
  // Report progress
  monitor.setTaskName("Stage 1...");
  // Do work...
  monitor.worked(30);
  
  // Check for cancellation
  if (monitor.isCanceled()) {
    throw new OperationCanceledException();
  }
  
  monitor.setTaskName("Stage 2...");
  // Do more work...
  monitor.worked(70);
  
} finally {
  // Always complete
  monitor.done();
}
```

--------------------------------

### Accessing Repository Configuration

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of retrieving repository configuration details. This involves accessing the IRepository interface.

```ABAP
DATA(lr_repository) = cl_abapgit_adt_api=>repository_service_factory( )->get_repository( '/path/to/local/repo' )
```

--------------------------------

### Monitor Usage Example

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

Demonstrates the lifecycle of an IProgressMonitor, including setting tasks, reporting work, checking for cancellation, and completing the task. Ensure to handle potential cancellations.

```java
IProgressMonitor monitor = new NullProgressMonitor();
monitor.beginTask("Cloning repository", 5);

try {
  monitor.setTaskName("Connecting to repository...");
  // Stage 1
  monitor.worked(1);
  
  monitor.setTaskName("Loading objects...");
  // Stage 2
  monitor.worked(2);
  
  if (monitor.isCanceled()) {
    throw new OperationCanceledException();
  }
  
  monitor.setTaskName("Finalizing...");
  // Stage 3
  monitor.worked(2);
  
} finally {
  monitor.done();
}
```

--------------------------------

### Push Repository Example

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates how to push local commits to a remote repository. This requires a properly configured remote and appropriate credentials.

```ABAP
DATA(\(lr_repo_service) = cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )

cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )->push(
  path = '/path/to/local/repo'
)
```

--------------------------------

### Usage Example for IAbapGitFile

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/StagingModel.md

Demonstrates how to iterate through IAbapGitFile objects, access file details, check their local states (added, modified, deleted), and fetch/compare local and remote file versions using a FileService.

```java
for (IAbapGitFile file : object.getFiles()) {
  System.out.println("File: " + file.getName() + 
                     " - Path: " + file.getPath());
  
  // Check if file was added, modified, or deleted
  if ("A".equals(file.getLocalState())) {
    System.out.println("  Added");
  } else if ("M".equals(file.getLocalState())) {
    System.out.println("  Modified");
  } else if ("D".equals(file.getLocalState())) {
    System.out.println("  Deleted");
  }
  
  // Compare versions
  String local = fileService.readLocalFileContents(
    file, destinationId);
  String remote = fileService.readRemoteFileContents(
    file, credentials, destinationId);
  
  String diff = calculateDiff(local, remote);
}
```

--------------------------------

### APACK Manifest File Structure

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

An example of an APACK manifest file in XML format, detailing package information and dependencies.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<apack>
  <groupId>com.example</groupId>
  <packageId>my-package</packageId>
  <version>1.0.0</version>
  <repositoryType>APACK</repositoryType>
  <gitUrl>https://github.com/example/my-package.git</gitUrl>
  
  <dependencies>
    <dependency>
      <groupId>com.dependency</groupId>
      <artifactId>dep-package</artifactId>
      <version>
        <minimum inclusive="true">1.0.0</minimum>
        <maximum inclusive="false">2.0.0</maximum>
      </version>
      <gitUrl>https://github.com/dependency/dep-package.git</gitUrl>
      <targetPackage>/DEPENDENCY/PACKAGE</targetPackage>
    </dependency>
  </dependencies>
</apack>
```

--------------------------------

### Developer Resources

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

This section provides resources for developers, including code examples, API signatures, and error patterns.

```APIDOC
## Developer Resources

Developers can find the following resources:

- **Code examples**: Available in `QUICK-REFERENCE.md`.
- **API signatures**: Detailed in `api-reference/` documents.
- **Error patterns**: Documented in `errors.md`.
- **Architecture details**: Available in `MODULE-ARCHITECTURE.md`.
```

--------------------------------

### Pull Repository Example

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Illustrates how to pull changes from a remote repository into a local one. This operation updates the local repository with the latest commits.

```ABAP
DATA(\(lr_repo_service) = cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )

cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )->pull(
  path = '/path/to/local/repo'
)
```

--------------------------------

### Accessing ABAP Object References

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of retrieving references to ABAP objects within the staging area or repository.

```ABAP
DATA(lr_abap_object) = cl_abapgit_adt_api=>staging_model( )->get_staging( '/path/to/local/repo' )->get_objects( )[ 1 ]->get_abap_object( )
```

--------------------------------

### Get All Linked Repositories

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Retrieves a collection of all abapGit repositories currently linked to the ABAP system. Requires a progress monitor.

```java
IRepositories getRepositories(IProgressMonitor monitor)
```

```java
IRepositoryService service = RepositoryServiceFactory.createRepositoryService(
  "SAP_SYSTEM", progressMonitor
);
IRepositories repositories = service.getRepositories(progressMonitor);
```

--------------------------------

### Handling Commit Messages

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Example of accessing commit message metadata, including author, date, and message content.

```ABAP
DATA(ls_commit_message) = cl_abapgit_adt_api=>commit_message( )
" Access ls_commit_message fields like author, date, message
```

--------------------------------

### Get APACK Manifest

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Retrieves the APACK manifest for a repository, including its descriptor and dependencies. Allows checking version compatibility.

```java
IApackManifest manifest = manifestService.getManifest(
  "https://github.com/user/repo.git",
  "refs/heads/master",
  "gituser",
  "gitpass",
  monitor
);

// Access descriptor
IApackManifest.IApackManifestDescriptor desc = manifest.getDescriptor();
System.out.println(desc.getGroupId());      // com.example
System.out.println(desc.getPackageId());    // my-package
System.out.println(desc.getVersion());      // 1.0.0

// Access dependencies
if (manifest.hasDependencies()) {
  for (IApackManifest.IApackDependency dep : desc.getDependencies()) {
    System.out.println(dep.getGroupId() + ":" + dep.getArtifactId());
    
    // Check version compatibility
    if (dep.getVersion().isVersionCompatible("1.5.0")) {
      System.out.println("Version 1.5.0 is compatible");
    }
  }
}
```

--------------------------------

### Repository Service Creation

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates how to create an instance of the Repository Service. This is a common pattern for interacting with repository operations.

```ABAP
DATA(\(lr_repo_service) = cl_abapgit_adt_api=>repository_service_factory( )->get_repository_service( )
```

--------------------------------

### Working with Repository Collections

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows how to retrieve and iterate over a collection of repositories using the IRepositories interface.

```ABAP
DATA(lr_repositories) = cl_abapgit_adt_api=>repository_service_factory( )->get_repositories( )
LOOP AT lr_repositories INTO DATA(ls_repository).
```

--------------------------------

### List Repositories

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Retrieves a list of all abapgit repositories configured in the system. Iterates through the list to print URL and branch name.

```java
IRepositories repositories = repoService.getRepositories(monitor);
for (IRepository repo : repositories.getRepositories()) {
  System.out.println(repo.getUrl() + " - " + repo.getBranchName());
}
```

--------------------------------

### Create abapGit ADT Services

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Instantiate various abapGit services for repository, external repository information, file content comparison, and APACK manifest management. Ensure the correct destination ID and progress monitor are provided.

```java
IFileService fileService = FileServiceFactory.createFileService();
IApackGitManifestService manifestService = ApackServiceFactory.createApackGitManifestService("DESTINATION_ID", progressMonitor);
// Repository service (main operations)
IRepositoryService repoService = RepositoryServiceFactory
  .createRepositoryService("DESTINATION_ID", progressMonitor);

// External repository info (branches, access mode)
IExternalRepositoryInfoService infoService = 
  RepositoryServiceFactory.createExternalRepositoryInfoService(
    "DESTINATION_ID", progressMonitor);

```

--------------------------------

### Handling Communication Errors

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Provides an example of how to catch and handle CommunicationException, which typically occurs due to network or protocol issues during API calls.

```ABAP
TRY.
    " API call that might throw CommunicationException
  CATCH cx_abapgit_communication_exception INTO DATA(lx_comm).
    " Handle communication error
ENDTRY.
```

--------------------------------

### Initialize Repository Service with Monitor

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

Use this pattern when integrating abapGit services within an Eclipse UI context, where an IProgressMonitor is readily available.

```java
IProgressMonitor monitor = ... // provided by Eclipse
IRepositoryService service = RepositoryServiceFactory.createRepositoryService(
  destinationId,
  monitor
);
```

--------------------------------

### File Comparison Workflow

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows how to compare file content using the File Service. This is useful for identifying differences between versions or local/remote states.

```ABAP
DATA(\(lr_file_service) = cl_abapgit_adt_api=>file_service_factory( )->get_file_service( )

DATA(lt_diff) = lr_file_service->compare_files(
  path1 = '/path/to/file1'
  path2 = '/path/to/file2'
)
```

--------------------------------

### Compare File Versions

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Reads file contents to compare local and remote versions. Provides methods to get both versions, only local, or only remote.

```java
// Get both local and remote content
List<String> contents = fileService.readFileContentsBatch(
  abapGitFile,
  credentials,
  "DESTINATION_ID"
);

String localContent = contents.get(0);
String remoteContent = contents.get(1);

// Get only local version
String local = fileService.readLocalFileContents(
  abapGitFile,
  "DESTINATION_ID"
);

// Get only remote version
String remote = fileService.readRemoteFileContents(
  abapGitFile,
  credentials,
  "DESTINATION_ID"
);
```

--------------------------------

### Catching OperationCanceledException in Java

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/errors.md

This example shows how to catch exceptions when a user cancels an operation via the progress monitor, allowing for cleanup of any partial state.

```java
try {
  IAbapGitStaging staging = service.stage(repository, credentials, monitor);
} catch (OperationCanceledException e) {
  System.out.println("Operation cancelled by user");
  // Clean up any partial state
}
```

--------------------------------

### Instantiate File Service

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/README.md

Instantiate the File Service, which is used for content comparison. This service follows the Singleton pattern and can be created without additional parameters.

```java
IFileService fileService = 
  FileServiceFactory.createFileService();
```

--------------------------------

### Get External Repository Information

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Fetches information about branches and specific branch details from a remote Git repository. Requires repository URL and user credentials.

```java
// Get all branches from a repository
IExternalRepositoryInfo repoInfo = infoService.getExternalRepositoryInfo(
  "https://github.com/user/repo.git",
  "username",
  "password",
  monitor
);

for (IBranch branch : repoInfo.getBranches()) {
  System.out.println("Branch: " + branch.getDisplayName());
  System.out.println("SHA1: " + branch.getSha1());
}

// Get specific branch details
IBranch branchInfo = infoService.getBranchInfo(
  repoInfo,
  "https://github.com/user/repo.git",
  "username",
  "password",
  "develop",
  "$ABAPGIT"
);
```

--------------------------------

### Working with Git Branches

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates how to retrieve and inspect Git branch information, including branch names and commit SHAs.

```ABAP
DATA(lr_branch) = cl_abapgit_adt_api=>repository_service_factory( )->get_repository( '/path/to/local/repo' )->get_branch( )
" Access lr_branch fields like name, commit_sha
```

--------------------------------

### FileService Singleton Instance

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

Demonstrates that all calls to createFileService() return the same instance, ensuring a singleton pattern.

```java
IFileService fs1 = FileServiceFactory.createFileService();
IFileService fs2 = FileServiceFactory.createFileService();
assert fs1 == fs2;  // true
```

--------------------------------

### Instantiate External Repository Info Service

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/README.md

Create an instance of the External Repository Info Service to retrieve information about remote repositories, such as branches and access modes. Requires a destination ID and a monitor object.

```java
IExternalRepositoryInfoService infoService = 
  RepositoryServiceFactory.createExternalRepositoryInfoService(destinationId, monitor);
```

--------------------------------

### Catching OutDatedClientException in Java

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/errors.md

Use this snippet to handle cases where the ADT client version is incompatible with the ABAP backend, typically requiring an update to the Eclipse ADT installation.

```java
try {
  IAbapGitStaging staging = service.stage(repository, credentials, monitor);
} catch (OutDatedClientException e) {
  System.err.println("Client version outdated. Please upgrade ADT.");
  // Notify user to update their Eclipse ADT installation
}
```

--------------------------------

### Maven Build Profile Selection

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

Use these Maven commands to build the project with specific profiles. The 'dev' profile is for development, while the 'prod' profile is the default for releases and includes blocking SpotBugs analysis.

```bash
# Build with dev profile
mvn clean install -Dprofile=dev

# Build with prod profile (default)
mvn clean install -Dprofile=prod
```

--------------------------------

### Instantiate APACK Manifest Service

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/README.md

Create an instance of the APACK Git Manifest Service for managing APACK manifests. Requires a destination ID and a monitor object.

```java
IApackGitManifestService manifestService = 
  ApackServiceFactory.createApackGitManifestService(destinationId, monitor);
```

--------------------------------

### Instantiate Repository Service

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/README.md

Use this factory method to create an instance of the Repository Service for major Git operations. Requires a destination ID and a monitor object.

```java
IRepositoryService repoService = 
  RepositoryServiceFactory.createRepositoryService(destinationId, monitor);
```

--------------------------------

### Using IAbapGitStaging for Commit Operations

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/StagingModel.md

Demonstrates how to retrieve staging information, set commit message details, and perform a push operation using the IAbapGitStaging interface. Requires the abapgit ADT service.

```java
IAbapGitStaging staging = service.stage(repository, credentials, monitor);

// Get unstaged modifications
IUnstagedObjects unstaged = staging.getUnstagedObjects();

// Get objects ready for commit
IStagedObjects staged = staging.getStagedObjects();

// Set commit message before push
IAbapGitCommitMessage message = staging.getCommitMessage();
message.setMessage("Bug fix for issue #123");
message.setCommitter("Jane Developer");
message.setEmail("jane@example.com");

// Perform push
service.push(monitor, staging, credentials, repository);
```

--------------------------------

### Handling IO Errors

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows how to catch and handle IOException, typically related to file read/write operations. Ensure file paths are correct and permissions are adequate.

```ABAP
TRY.
    " API call that might throw IOException
  CATCH cx_abapgit_io_exception INTO DATA(lx_io).
    " Handle IO error
ENDTRY.
```

--------------------------------

### Factory Method: createRepositoryService

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Creates an instance of the IRepositoryService. This is the entry point for interacting with repository operations.

```APIDOC
## Factory Method: createRepositoryService

### Description
Creates an instance of the `IRepositoryService` using the provided ADT destination and progress monitor.

### Signature
```java
IRepositoryService createRepositoryService(
  String destinationId,
  IProgressMonitor monitor
)
```

### Parameters
#### Path Parameters
- **destinationId** (String) - Required - The ADT destination identifier for the ABAP system
- **monitor** (IProgressMonitor) - Required - Eclipse progress monitor for long-running operations

### Returns
`IRepositoryService` - Service instance or null if the destination URI cannot be discovered.
```

--------------------------------

### Create Repository Service Instance

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Use the factory method to create an instance of IRepositoryService. This requires the ADT destination ID and a progress monitor for long-running operations.

```java
IRepositoryService createRepositoryService(
  String destinationId, 
  IProgressMonitor monitor
)
```

--------------------------------

### Clone Multiple Repositories in Batch

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Clones a collection of repositories simultaneously. Requires a collection of repositories and a progress monitor.

```java
void cloneRepositories(IRepositories repositories, IProgressMonitor monitor)
```

--------------------------------

### Create ApackGitManifestService Instance

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/ApackManifestService.md

Use this factory method to create an instance of IApackGitManifestService. Requires an ADT destination ID and an Eclipse progress monitor.

```java
IApackGitManifestService createApackGitManifestService(
  String destinationId, 
  IProgressMonitor monitor
)
```

--------------------------------

### Create ExternalRepositoryInfoService Instance

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/ExternalRepositoryInfoService.md

Instantiates the ExternalRepositoryInfoService using a destination ID and a progress monitor. This service is used to query external Git repository metadata.

```java
IExternalRepositoryInfoService createExternalRepositoryInfoService(
  String destinationId, 
  IProgressMonitor monitor
)
```

--------------------------------

### Handling Resource Errors

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows how to catch and handle ResourceException, which indicates problems with backend resources such as file system access or database issues.

```ABAP
TRY.
    " API call that might throw ResourceException
  CATCH cx_abapgit_resource_exception INTO DATA(lx_resource).
    " Handle resource error
ENDTRY.
```

--------------------------------

### Enable Debug Logging for ABAP Git Backend

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Enable debug logging for the ABAP Git backend by adding a specific entry to the .launch file.

```text
Add org.abapgit.adt.backend=DEBUG to .launch file
```

--------------------------------

### Create FileService Instance

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/FileService.md

Obtain a singleton instance of the FileService using the factory method. This instance is used to interact with file content operations.

```Java
IFileService fileService = FileServiceFactory.createFileService();
```

--------------------------------

### Prepare for Push Operation

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/StagingModel.md

Checks if there are staged objects and a commit message before initiating a push. Ensures that the staging area is not empty and a message is provided, which are prerequisites for a successful push.

```java
if (staging.getStagedObjects().getObjects().isEmpty()) {
  System.out.println("Nothing to commit");
  return;
}

IAbapGitCommitMessage msg = staging.getCommitMessage();
if (msg.getMessage() == null || msg.getMessage().isEmpty()) {
  System.err.println("Commit message required");
  return;
}

service.push(monitor, staging, credentials, repository);
```

--------------------------------

### Using Access Mode Enum

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates the usage of the AccessMode enum, which defines read and write access levels for repository operations.

```ABAP
DATA(lv_access_mode) = abap_enum=>get_value( 'CL_ABAPGIT_ADT_API=>ACCESS_MODE'  " Read access
  name = 'READ'
).
```

--------------------------------

### Handle Operation Cancellation

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Demonstrates how to handle an operation cancellation exception during staging or other repository operations. Includes cleanup logic.

```java
try {
  IAbapGitStaging staging = repoService.stage(
    repository,
    credentials,
    monitor
  );
  
  // Do work...
  
} catch (OperationCanceledException e) {
  System.out.println("User cancelled operation");
  // Cleanup
}
```

--------------------------------

### Test Infrastructure Directory Structure

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/MODULE-ARCHITECTURE.md

This snippet outlines the directory structure for the test infrastructure. It includes the Maven configuration and indicates the presence of plugin and integration tests.

```tree
test/
├── pom.xml (Maven configuration for tests)
└── Plugin tests for backend and UI modules
└── Integration tests for end-to-end scenarios
```

--------------------------------

### Run Spotbugs Locally with Maven

Source: https://github.com/abapgit/adt_frontend/blob/master/DEV-GUIDELINES.md

Execute the Spotbugs static analysis tool locally to verify code quality before submitting a Pull Request. This command cleans the project and runs the verification phase.

```bash
mvn clean verify
```

--------------------------------

### Retrieve and Parse .apack Manifest

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/ApackManifestService.md

Retrieves and parses the .apack manifest file from a Git repository for a specific branch. Provide the repository URL, branch, Git credentials, and a progress monitor.

```java
IApackGitManifestService service = ApackServiceFactory
  .createApackGitManifestService("SAP_SYSTEM", monitor);

IApackManifest manifest = service.getManifest(
  "https://github.com/myorg/mypackage.git",
  "refs/heads/master",
  "gituser",
  "gitpass",
  monitor
);

// Access package descriptor
IApackManifest.IApackManifestDescriptor descriptor = manifest.getDescriptor();
String groupId = descriptor.getGroupId();
String packageId = descriptor.getPackageId();
String version = descriptor.getVersion();

// Check for dependencies
if (manifest.hasDependencies()) {
  for (IApackManifest.IApackDependency dep : descriptor.getDependencies()) {
    String depGroupId = dep.getGroupId();
    String depArtifactId = dep.getArtifactId();
    String depVersion = dep.getVersion().getMinimum();
  }
}
```

--------------------------------

### Load Staging Data for a Repository

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Loads staging data, including modified objects, for a given repository without committing changes. Requires the repository, external repository credentials, and a progress monitor. Can throw various exceptions like CommunicationException or OutDatedClientException.

```java
IAbapGitStaging stage(
  IRepository repository, 
  IExternalRepositoryInfoRequest credentials, 
  IProgressMonitor monitor
) throws CommunicationException, ResourceException, OperationCanceledException, OutDatedClientException
```

```java
IAbapGitStaging staging = service.stage(
  repository, 
  credentialsRequest, 
  monitor
);
```

--------------------------------

### Retrieving Remote Repository Information

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Shows how to fetch metadata for a remote repository, such as branches and tags, using IExternalRepositoryInfoService.

```ABAP
DATA(lr_external_info) = cl_abapgit_adt_api=>external_repository_info_factory( )->get_external_repository_info_service( )
DATA(ls_repo_info) = lr_external_info->get_repository_info( 'https://github.com/abapGit/abapGit.git' )
```

--------------------------------

### API Reference Services

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

This section outlines the available API reference services for various operations within the abapgit ADT Frontend. These services cover repository operations, remote metadata, file comparison, package management, and staging.

```APIDOC
## API Reference Services

This section provides access to specific service documentation for various tasks:

- **Repository operations**: Consult `api-reference/RepositoryService.md`
- **Remote metadata**: Consult `api-reference/ExternalRepositoryInfoService.md`
- **File comparison**: Consult `api-reference/FileService.md`
- **Package management**: Consult `api-reference/ApackManifestService.md`
- **Staging operations**: Consult `api-reference/StagingModel.md`
```

--------------------------------

### Singleton Pattern for FileService

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/MODULE-ARCHITECTURE.md

Ensures a single, shared instance of the FileService for memory-efficient and thread-safe resource sharing. Use this method to obtain the singleton instance.

```java
private static IFileService instance;

public static IFileService createFileService() {
  if (instance == null) {
    instance = new FileService();
  }
  return instance;
}
```

--------------------------------

### Check Backend Version via Repository Atom Links

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Determine the backend version by checking for the presence of RELATION_PULL_WITH_BG_RUN in repository Atom links.

```text
Check RELATION_PULL_WITH_BG_RUN presence in repository Atom links
```

--------------------------------

### getRepositories

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Retrieves a collection of all abapGit repositories currently linked to the ABAP system.

```APIDOC
## getRepositories

### Description
Retrieves all abapGit repositories currently linked to the system.

### Signature
```java
IRepositories getRepositories(IProgressMonitor monitor)
```

### Parameters
#### Path Parameters
- **monitor** (IProgressMonitor) - Required - Progress monitor for the operation

### Returns
`IRepositories` - Collection of all linked repositories

### Example
```java
IRepositoryService service = RepositoryServiceFactory.createRepositoryService(
  "SAP_SYSTEM", progressMonitor
);
IRepositories repositories = service.getRepositories(progressMonitor);
```
```

--------------------------------

### Destination ID Best Practices

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Illustrates how to correctly define and use destination IDs in Eclipse ADT. It's recommended to use IDs that match configured destinations for clarity and consistency. Verify destination existence in Preferences.

```java
// Good: from Eclipse ADT destination
String destinationId = "SAP_SYSTEM";  // Matches configured destination

// Also valid
String destinationId = "DEV";
String destinationId = "QA_SYSTEM";

// Verify destination exists
Windows → Preferences → ABAP Development → Destinations
```

--------------------------------

### Accessing Staging Area

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Illustrates how to access and manipulate the staging area using the StagingModel. This involves working with staged objects and files.

```ABAP
DATA(lt_staging) = cl_abapgit_adt_api=>staging_model( )->get_staging(
  path = '/path/to/local/repo'
)
```

--------------------------------

### Create SubProgressMonitor Programmatically

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

Create a SubProgressMonitor to report progress within a larger task, linking it to a parent monitor.

```java
IProgressMonitor monitor = new SubProgressMonitor(parentMonitor, 100);
monitor.beginTask("Loading repositories", 100);
```

--------------------------------

### getManifest

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/ApackManifestService.md

Retrieves and parses the .apack manifest file from a Git repository for a specific branch.

```APIDOC
## getManifest

### Description
Retrieves and parses the .apack manifest file from a Git repository for a specific branch.

### Method Signature
```java
IApackManifest getManifest(
  String url,
  String branch,
  String user,
  String password,
  IProgressMonitor monitor
)
```

### Parameters
#### Path Parameters
- **url** (String) - Required - Git repository URL
- **branch** (String) - Required - Branch name (e.g., "master" or "refs/heads/develop")
- **user** (String) - Required - Git repository username
- **password** (String) - Required - Git repository password or token
- **monitor** (IProgressMonitor) - Required - Progress monitor

### Returns
- **IApackManifest** - Parsed manifest containing package metadata and dependencies

### Example
```java
IApackGitManifestService service = ApackServiceFactory
  .createApackGitManifestService("SAP_SYSTEM", monitor);

IApackManifest manifest = service.getManifest(
  "https://github.com/myorg/mypackage.git",
  "refs/heads/master",
  "gituser",
  "gitpass",
  monitor
);

// Access package descriptor
IApackManifest.IApackManifestDescriptor descriptor = manifest.getDescriptor();
String groupId = descriptor.getGroupId();
String packageId = descriptor.getPackageId();
String version = descriptor.getVersion();

// Check for dependencies
if (manifest.hasDependencies()) {
  for (IApackManifest.IApackDependency dep : descriptor.getDependencies()) {
    String depGroupId = dep.getGroupId();
    String depArtifactId = dep.getArtifactId();
    String depVersion = dep.getVersion().getMinimum();
  }
}
```
```

--------------------------------

### Factory Classes in org.abapgit.adt.backend

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/MODULE-ARCHITECTURE.md

Shows the factory classes available in the backend module. These are used to obtain instances of the service interfaces.

```plaintext
├── RepositoryServiceFactory
├── ApackServiceFactory
└── FileServiceFactory
```

--------------------------------

### cloneRepositories

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Clones multiple abapGit repositories in a single batch operation.

```APIDOC
## cloneRepositories

### Description
Clones multiple repositories in batch.

### Signature
```java
void cloneRepositories(IRepositories repositories, IProgressMonitor monitor)
```

### Parameters
#### Path Parameters
- **repositories** (IRepositories) - Required - Collection of repositories to clone
- **monitor** (IProgressMonitor) - Required - Progress monitor

```

--------------------------------

### UI Layer Directory Structure

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/MODULE-ARCHITECTURE.md

This snippet shows the directory structure for the UI layer of the abapgit ADT frontend. It details the organization of views, actions, comparison components, dialogs, and localization resources.

```tree
ui/
├── AbapGitUIPlugin (plugin activator)
├── internal/
│   ├── repositories/
│   │   ├── AbapGitView (main repository view)
│   │   ├── IAbapGitRepositoriesView (interface)
│   │   ├── IRepositoryModifiedObjects
│   │   ├── RepositoryModifiedObjects
│   │   └── actions/
│   │       ├── OpenRepositoryAction
│   │       ├── SwitchbranchAction
│   │       └── ... (various actions)
│   ├── staging/
│   │   ├── AbapGitStagingView (staging area view)
│   │   ├── IAbapGitStagingView (interface)
│   │   ├── AbapGitStagingContentProvider
│   │   ├── AbapGitStagingLabelProvider
│   │   ├── AbapGitStagingGrouping
│   │   ├── IAbapGitStagingGrouping
│   │   ├── AbapGitStagingObjectMenuFactory
│   │   ├── actions/
│   │   │   ├── CompareAction (file diff)
│   │   │   ├── OpenObjectAction
│   │   │   ├── OpenPackageAction
│   │   │   └── CopyNameAction
│   │   ├── compare/
│   │   │   ├── AbapGitCompareInput
│   │   │   ├── AbapGitCompareItem
│   │   │   └── (Eclipse compare framework integration)
│   │   ├── util/
│   │   │   ├── AbapGitStagingService (staging operations)
│   │   │   ├── AbapGitFileEditorInput (file editor integration)
│   │   │   ├── FileStagingModeUtil
│   │   │   ├── AbapGitStagingTreeFilter
│   │   │   ├── AbapGitStagingTreeComparator
│   │   │   └── AbapGitStagingGroupingUtil
│   ├── dialogs/
│   │   ├── AbapGitDialogObjLog (object log viewer)
│   │   ├── AbapGitStagingCredentialsDialog
│   │   └── ... (various dialogs)
│   └── i18n/
│       └── Messages (localization strings)
```

--------------------------------

### Factory Methods

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Factory methods are provided to instantiate the various services offered by the abapGit ADT Frontend. This includes methods for creating instances of RepositoryService, ApackService, and FileService.

```APIDOC
## Factory Methods

### Description
Factory methods are used to obtain instances of the abapGit ADT Frontend services. This ensures proper initialization and management of service lifecycles.

### Factories
- **RepositoryServiceFactory**: Provides factory methods for `IRepositoryService`.
- **ApackServiceFactory**: Provides factory methods for `IApackManifestService`.
- **FileServiceFactory**: Provides a singleton factory method for `IFileService`.

### Usage
Developers should use these factory methods to get service instances instead of directly instantiating service classes.
```

--------------------------------

### IAbapGitStaging Interface

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/StagingModel.md

The root staging container interface provides access to unstaged objects, staged objects, ignored objects, and commit message details. It also includes navigation links.

```APIDOC
## Interface IAbapGitStaging

### Description
The root staging container with all object categories and commit metadata. It represents the current state of objects that can be committed to the repository.

### Module
`org.abapgit.adt.backend.model.abapgitstaging`

### Properties
- **unstagedObjects** (IUnstagedObjects) - Required - Objects locally modified, not selected for commit
- **stagedObjects** (IStagedObjects) - Required - Objects selected for commit
- **ignoredObjects** (IIgnoredObjects) - Required - Objects to exclude from version control
- **commitMessage** (IAbapGitCommitMessage) - Required - Commit message and author info
- **links** (EList<IAtomLink>) - Required - Navigation links (push endpoint, etc.)

### Usage Example
```java
// Assuming 'service' is an initialized service object and 'repository', 'credentials', 'monitor' are defined
IAbapGitStaging staging = service.stage(repository, credentials, monitor);

// Get unstaged modifications
IUnstagedObjects unstaged = staging.getUnstagedObjects();

// Get objects ready for commit
IStagedObjects staged = staging.getStagedObjects();

// Set commit message before push
IAbapGitCommitMessage message = staging.getCommitMessage();
message.setMessage("Bug fix for issue #123");
message.setCommitter("Jane Developer");
message.setEmail("jane@example.com");

// Perform push
service.push(monitor, staging, credentials, repository);
```
```

--------------------------------

### Create NullProgressMonitor Programmatically

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/configuration.md

Instantiate a NullProgressMonitor for non-UI contexts or when explicit progress tracking is not required.

```java
IProgressMonitor monitor = new NullProgressMonitor();
```

--------------------------------

### Handling Package Reference Not Found Errors

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

Demonstrates catching PackageRefNotFoundException, an error indicating that a required package reference could not be located. Verify package integrity and paths.

```ABAP
TRY.
    " API call that might throw PackageRefNotFoundException
  CATCH cx_abapgit_package_ref_not_found INTO DATA(lx_pkg_ref).
    " Handle package ref not found error
ENDTRY.
```

--------------------------------

### Staging and Commits

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/INDEX.md

Operations for loading the staging area, committing changes, and validating the connection.

```APIDOC
## Staging and Commits

### Description
Operations for loading the staging area, committing changes, and validating the connection.

### Methods
- `IRepositoryService.stage()`
- `IRepositoryService.push()`
- `IRepositoryService.repositoryChecks()`
```

--------------------------------

### FileServiceFactory.createFileService()

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/FileService.md

Factory method to create a singleton instance of the FileService. This service is used to access file content comparison functionalities.

```APIDOC
## createFileService

### Description
Factory method to create a singleton instance of the FileService. This service is used to access file content comparison functionalities.

### Method
Factory Method

### Returns
`IFileService` — Singleton instance of FileService

### Example
```java
IFileService fileService = FileServiceFactory.createFileService();
```
```

--------------------------------

### createApackGitManifestService

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/ApackManifestService.md

Factory method to create an instance of IApackGitManifestService.

```APIDOC
## createApackGitManifestService

### Description
Factory method to create an instance of IApackGitManifestService.

### Method Signature
```java
IApackGitManifestService createApackGitManifestService(
  String destinationId,
  IProgressMonitor monitor
)
```

### Parameters
#### Path Parameters
- **destinationId** (String) - Required - The ADT destination identifier for the ABAP system
- **monitor** (IProgressMonitor) - Required - Eclipse progress monitor for the operation

### Returns
- **IApackGitManifestService** - Service instance

### Source
`org.abapgit.adt.backend:ApackServiceFactory`
```

--------------------------------

### Exception Types

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

The documentation covers various exception types that can be raised by the abapGit ADT Frontend, including communication errors, resource issues, version incompatibilities, and operation cancellations.

```APIDOC
## Exception Types

### Description
This section outlines the exception types that may be thrown by the abapGit ADT Frontend services. Proper handling of these exceptions is essential for robust application development.

### Documented Exceptions
- **CommunicationException**: For network or protocol errors.
- **ResourceException**: For backend resource-related errors.
- **OutDatedClientException**: Indicates version incompatibility.
- **OperationCanceledException**: Raised when an operation is canceled by the user.
- **IOException**: For errors during file read operations.
- **PackageRefNotFoundException**: A UI-level error indicating a package reference was not found.

### Usage
Developers should implement appropriate error handling mechanisms, such as try-catch blocks, to gracefully manage these exceptions and provide meaningful feedback to the user or system.
```

--------------------------------

### Show Progress View in Eclipse

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Open the Progress view in Eclipse to monitor ongoing operations.

```text
Eclipse: Window → Show View → Progress
```

--------------------------------

### Package Manifest Parsing

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/INDEX.md

Parses the .apack file to retrieve package manifest information.

```APIDOC
## Package Manifest Parsing

### Description
Parses the .apack file to retrieve package manifest information.

### Method
- `IApackGitManifestService.getManifest()`
```

--------------------------------

### Retrieve External Repository Information

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/ExternalRepositoryInfoService.md

Fetches metadata for a Git repository, including available branches and access mode (read-only/read-write). Requires repository URL, credentials, and a progress monitor.

```java
IExternalRepositoryInfoService service = RepositoryServiceFactory
  .createExternalRepositoryInfoService("SAP_SYSTEM", monitor);

IExternalRepositoryInfo repoInfo = service.getExternalRepositoryInfo(
  "https://github.com/myorg/myrepo.git",
  "username",
  "password",
  monitor
);

// Access available branches
for (IBranch branch : repoInfo.getBranches()) {
  System.out.println("Branch: " + branch.getName());
}
```

--------------------------------

### Validate repository connectivity and credentials

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/api-reference/RepositoryService.md

Validates repository connectivity, credentials, and compatibility. Requires a progress monitor, credentials, and the repository to validate.

```java
void repositoryChecks(
  IProgressMonitor monitor, 
  IExternalRepositoryInfoRequest credentials, 
  IRepository repository
) throws CommunicationException, ResourceException, OperationCanceledException, OutDatedClientException
```

--------------------------------

### Public Interfaces of org.abapgit.adt.backend

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/MODULE-ARCHITECTURE.md

Lists the main public interfaces provided by the backend service layer for Git operations and repository management. These are the primary entry points for interacting with the backend functionality.

```plaintext
org.abapgit.adt.backend
├── IRepositoryService (main service)
├── IExternalRepositoryInfoService (branch/remote info)
├── IFileService (file content comparison)
├── IApackGitManifestService (APACK manifest parsing)
└── IApackManifest (manifest data model)
```

--------------------------------

### Public Services

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/DOCUMENTATION-SUMMARY.txt

The abapGit ADT Frontend exposes several public services for interacting with ABAP repositories, remote repository information, file operations, and package manifests. These services are the primary interface for developers.

```APIDOC
## Public Services

### Description
These services provide the core functionality for interacting with the abapGit ADT Frontend. They cover repository management, remote repository queries, file operations, and package manifest handling.

### Services
- **IRepositoryService**: Core repository operations.
- **IExternalRepositoryInfoService**: Remote metadata and branches.
- **IFileService**: File content comparison.
- **IApackManifestService**: Package manifest parsing and validation.

### Usage
Developers can create instances of these services using factory methods and then invoke their public API methods to perform various Git-related operations within the ABAP Development Tools (ADT) environment.
```

--------------------------------

### Clone Repository

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/QUICK-REFERENCE.md

Clones a Git repository into the ABAP system. Requires repository URL, branch, target package, folder logic, transport request, user credentials, and a monitor.

```java
IAbapObjects clonedObjects = repoService.cloneRepository(
  "https://github.com/user/repo.git",     // url
  "refs/heads/master",                     // branch
  "$ABAPGIT",                              // targetPackage
  "PREFIX",                                // folderLogic
  "PROJ000001",                            // transportRequest
  "gituser",                               // user
  "gitpassword",                           // password
  monitor
);
```

--------------------------------

### Exception Hierarchy

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/INDEX.md

Illustrates the inheritance structure of exceptions used within the abapgit ADT frontend, extending from Java's Throwable and Exception classes.

```plaintext
java.lang.Throwable
├── java.lang.Exception
│   ├── com.sap.adt.communication.exceptions.CommunicationException
│   ├── com.sap.adt.communication.resources.ResourceException
│   ├── com.sap.adt.compatibility.exceptions.OutDatedClientException
│   ├── java.io.IOException
│   └── org.abapgit.adt.ui.internal.repositories.exceptions.PackageRefNotFoundException
│
└── org.eclipse.core.runtime.OperationCanceledException
    (extends RuntimeException)
```

--------------------------------

### Internal Implementation Classes in org.abapgit.adt.backend

Source: https://github.com/abapgit/adt_frontend/blob/master/_autodocs/MODULE-ARCHITECTURE.md

Lists the internal implementation classes within the backend module. These classes handle the core logic for service discovery, repository operations, and data handling.

```plaintext
internal/
├── AbapGitDiscovery (service endpoint discovery)
├── RepositoryService (IRepositoryService implementation)
├── ExternalRepositoryInfoService (info service impl)
├── FileService (file content impl)
├── ApackGitManifestService (manifest service impl)
├── *ContentHandler* (XML serialization/deserialization)
└── *Request* (request/response models)
```