@daytonaio/sdk 0.9.2 → 0.10.0

package/dist/Git.d.ts

@@ -1,67 +1,215 @@
-import { Workspace as WorkspaceInstance, ToolboxApi, ListBranchResponse, GitStatus } from '@daytonaio/api-client';
-import { Workspace } from './Workspace';
 /**
- * Provides Git operations within a workspace
- * @class Git
+ * The Daytona SDK provides built-in Git support. This guide covers all available Git
+ * operations and best practices. Daytona SDK provides an option to clone, check status,
+ * and manage Git repositories in Sandboxes. You can interact with Git repositories using
+ * the `git` module.
+ *
+ * @module Git
+ *
+ * @example
+ * // Basic Git workflow
+ * // Create and initialize workspace
+ * const workspace = await daytona.create();
+ *
+ * // Clone a repository
+ * await workspace.git.clone(
+ *   'https://github.com/user/repo.git',
+ *   '/workspace/repo'
+ * );
+ *
+ * // Make some changes
+ * await workspace.fs.uploadFile(
+ *   '/workspace/repo/test.txt',
+ *   new File([Buffer.from('Hello, World!')], 'test.txt')
+ * );
+ *
+ * // Stage and commit changes
+ * await workspace.git.add('/workspace/repo', ['test.txt']);
+ * await workspace.git.commit(
+ *   '/workspace/repo',
+ *   'Add test file',
+ *   'John Doe',
+ *   'john@example.com'
+ * );
+ *
+ * // Push changes (with authentication)
+ * await workspace.git.push(
+ *   '/workspace/repo',
+ *   'user',
+ *   'token'
+ * );
+ *
  */
+import { ToolboxApi, ListBranchResponse, GitStatus } from '@daytonaio/api-client';
+import { Workspace, WorkspaceInstance } from './Workspace';
 export declare class Git {
     private readonly workspace;
     private readonly toolboxApi;
     private readonly instance;
     constructor(workspace: Workspace, toolboxApi: ToolboxApi, instance: WorkspaceInstance);
     /**
-     * Stages files for commit
-     * @param {string} path - Repository path
-     * @param {string[]} files - Array of file paths to stage
+     * Stages files for commit.
+     *
+     * This method stages the specified files for the next commit, similar to
+     * running 'git add' on the command line.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @param {string[]} files - List of file paths or directories to stage, relative to the repository root
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Stage a single file
+     * await git.add('/workspace/repo', ['file.txt']);
+     *
+     * @example
+     * // Stage whole repository
+     * await git.add('/workspace/repo', ['.']);
      */
     add(path: string, files: string[]): Promise<void>;
     /**
-     * Lists branches in the repository
-     * @param {string} path - Repository path
-     * @returns {Promise<ListBranchResponse>} List of branches
+     * List branches in the repository.
+     *
+     * This method returns information about all branches in the repository.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @returns {Promise<ListBranchResponse>} List of branches in the repository
+     *
+     * @example
+     * const response = await git.branches('/workspace/repo');
+     * console.log(`Branches: ${response.branches}`);
      */
     branches(path: string): Promise<ListBranchResponse>;
     /**
-     * Clones a Git repository
-     * @param {string} url - Repository URL
-     * @param {string} path - Destination path
-     * @param {string} [branch] - Branch to clone
-     * @param {string} [commitId] - Specific commit to clone
+     * Clones a Git repository.
+     *
+     * This method clones a Git repository into the specified path. It supports
+     * cloning specific branches or commits, and can authenticate with the remote
+     * repository if credentials are provided.
+     *
+     * @param {string} url - Repository URL to clone from
+     * @param {string} path - Absolute path where the repository should be cloned
+     * @param {string} [branch] - Specific branch to clone. If not specified, clones the default branch
+     * @param {string} [commitId] - Specific commit to clone. If specified, the repository will be left in a detached HEAD state at this commit
      * @param {string} [username] - Git username for authentication
-     * @param {string} [password] - Git password/token for authentication
+     * @param {string} [password] - Git password or token for authentication
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Clone the default branch
+     * await git.clone(
+     *   'https://github.com/user/repo.git',
+     *   '/workspace/repo'
+     * );
+     *
+     * @example
+     * // Clone a specific branch with authentication
+     * await git.clone(
+     *   'https://github.com/user/private-repo.git',
+     *   '/workspace/private',
+     *   branch='develop',
+     *   username='user',
+     *   password='token'
+     * );
+     *
+     * @example
+     * // Clone a specific commit
+     * await git.clone(
+     *   'https://github.com/user/repo.git',
+     *   '/workspace/repo-old',
+     *   commitId='abc123'
+     * );
      */
     clone(url: string, path: string, branch?: string, commitId?: string, username?: string, password?: string): Promise<void>;
     /**
-     * Creates a new commit with staged changes
-     * @param {string} path - Repository path
-     * @param {string} message - Commit message
-     * @param {string} author - Author name
-     * @param {string} email - Author email
+     * Commits staged changes.
+     *
+     * This method creates a new commit with the staged changes. Make sure to stage
+     * changes using the add() method before committing.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @param {string} message - Commit message describing the changes
+     * @param {string} author - Name of the commit author
+     * @param {string} email - Email address of the commit author
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Stage and commit changes
+     * await git.add('/workspace/repo', ['README.md']);
+     * await git.commit(
+     *   '/workspace/repo',
+     *   'Update documentation',
+     *   'John Doe',
+     *   'john@example.com'
+     * );
      */
     commit(path: string, message: string, author: string, email: string): Promise<void>;
     /**
-     * Pushes local commits to remote repository
-     * @param {string} path - Repository path
+     * Push local changes to the remote repository.
+     *
+     * This method pushes committed changes to the remote repository. If the remote
+     * requires authentication, username and password/token must be provided.
+     *
+     * @param {string} path - Absolute path to the Git repository root
      * @param {string} [username] - Git username for authentication
-     * @param {string} [password] - Git password/token for authentication
+     * @param {string} [password] - Git password or token for authentication
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Push to a public repository
+     * await git.push('/workspace/repo');
+     *
+     * @example
+     * // Push to a private repository
+     * await git.push(
+     *   '/workspace/repo',
+     *   'user',
+     *   'token'
+     * );
      */
     push(path: string, username?: string, password?: string): Promise<void>;
     /**
-     * Pulls changes from remote repository
-     * @param {string} path - Repository path
+     * Pulls changes from the remote repository.
+     *
+     * This method fetches and merges changes from the remote repository. If the remote
+     * requires authentication, username and password/token must be provided.
+     *
+     * @param {string} path - Absolute path to the Git repository root
      * @param {string} [username] - Git username for authentication
-     * @param {string} [password] - Git password/token for authentication
+     * @param {string} [password] - Git password or token for authentication
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Pull from a public repository
+     * await git.pull('/workspace/repo');
+     *
+     * @example
+     * // Pull from a private repository
+     * await git.pull(
+     *   '/workspace/repo',
+     *   'user',
+     *   'token'
+     * );
      */
     pull(path: string, username?: string, password?: string): Promise<void>;
     /**
-     * Gets the current Git repository status
-     * @param {string} path - Repository path
-     * @returns {Promise<GitStatus>} Repository status information
+     * Gets the current status of the Git repository.
+     *
+     * This method returns information about the current state of the repository,
+     * including staged and unstaged changes, current branch, and untracked files.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @returns {Promise<GitStatus>} Current repository status including:
+     *                               - currentBranch: Name of the current branch
+     *                               - ahead: Number of commits ahead of the remote branch
+     *                               - behind: Number of commits behind the remote branch
+     *                               - branchPublished: Whether the branch has been published to the remote repository
+     *                               - fileStatus: List of file statuses
+     *
+     * @example
+     * const status = await workspace.git.status('/workspace/repo');
+     * console.log(`Current branch: ${status.currentBranch}`);
+     * console.log(`Commits ahead: ${status.ahead}`);
+     * console.log(`Commits behind: ${status.behind}`);
      */
     status(path: string): Promise<GitStatus>;
 }

package/dist/Git.js

@@ -1,10 +1,48 @@
 "use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Git = void 0;
 /**
- * Provides Git operations within a workspace
- * @class Git
+ * The Daytona SDK provides built-in Git support. This guide covers all available Git
+ * operations and best practices. Daytona SDK provides an option to clone, check status,
+ * and manage Git repositories in Sandboxes. You can interact with Git repositories using
+ * the `git` module.
+ *
+ * @module Git
+ *
+ * @example
+ * // Basic Git workflow
+ * // Create and initialize workspace
+ * const workspace = await daytona.create();
+ *
+ * // Clone a repository
+ * await workspace.git.clone(
+ *   'https://github.com/user/repo.git',
+ *   '/workspace/repo'
+ * );
+ *
+ * // Make some changes
+ * await workspace.fs.uploadFile(
+ *   '/workspace/repo/test.txt',
+ *   new File([Buffer.from('Hello, World!')], 'test.txt')
+ * );
+ *
+ * // Stage and commit changes
+ * await workspace.git.add('/workspace/repo', ['test.txt']);
+ * await workspace.git.commit(
+ *   '/workspace/repo',
+ *   'Add test file',
+ *   'John Doe',
+ *   'john@example.com'
+ * );
+ *
+ * // Push changes (with authentication)
+ * await workspace.git.push(
+ *   '/workspace/repo',
+ *   'user',
+ *   'token'
+ * );
+ *
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Git = void 0;
 class Git {
     constructor(workspace, toolboxApi, instance) {
         this.workspace = workspace;
@@ -12,10 +50,22 @@ class Git {
         this.instance = instance;
     }
     /**
-     * Stages files for commit
-     * @param {string} path - Repository path
-     * @param {string[]} files - Array of file paths to stage
+     * Stages files for commit.
+     *
+     * This method stages the specified files for the next commit, similar to
+     * running 'git add' on the command line.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @param {string[]} files - List of file paths or directories to stage, relative to the repository root
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Stage a single file
+     * await git.add('/workspace/repo', ['file.txt']);
+     *
+     * @example
+     * // Stage whole repository
+     * await git.add('/workspace/repo', ['.']);
      */
     async add(path, files) {
         await this.toolboxApi.gitAddFiles(this.instance.id, {
@@ -24,23 +74,60 @@ class Git {
         });
     }
     /**
-     * Lists branches in the repository
-     * @param {string} path - Repository path
-     * @returns {Promise<ListBranchResponse>} List of branches
+     * List branches in the repository.
+     *
+     * This method returns information about all branches in the repository.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @returns {Promise<ListBranchResponse>} List of branches in the repository
+     *
+     * @example
+     * const response = await git.branches('/workspace/repo');
+     * console.log(`Branches: ${response.branches}`);
      */
     async branches(path) {
         const response = await this.toolboxApi.gitListBranches(this.instance.id, path);
         return response.data;
     }
     /**
-     * Clones a Git repository
-     * @param {string} url - Repository URL
-     * @param {string} path - Destination path
-     * @param {string} [branch] - Branch to clone
-     * @param {string} [commitId] - Specific commit to clone
+     * Clones a Git repository.
+     *
+     * This method clones a Git repository into the specified path. It supports
+     * cloning specific branches or commits, and can authenticate with the remote
+     * repository if credentials are provided.
+     *
+     * @param {string} url - Repository URL to clone from
+     * @param {string} path - Absolute path where the repository should be cloned
+     * @param {string} [branch] - Specific branch to clone. If not specified, clones the default branch
+     * @param {string} [commitId] - Specific commit to clone. If specified, the repository will be left in a detached HEAD state at this commit
      * @param {string} [username] - Git username for authentication
-     * @param {string} [password] - Git password/token for authentication
+     * @param {string} [password] - Git password or token for authentication
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Clone the default branch
+     * await git.clone(
+     *   'https://github.com/user/repo.git',
+     *   '/workspace/repo'
+     * );
+     *
+     * @example
+     * // Clone a specific branch with authentication
+     * await git.clone(
+     *   'https://github.com/user/private-repo.git',
+     *   '/workspace/private',
+     *   branch='develop',
+     *   username='user',
+     *   password='token'
+     * );
+     *
+     * @example
+     * // Clone a specific commit
+     * await git.clone(
+     *   'https://github.com/user/repo.git',
+     *   '/workspace/repo-old',
+     *   commitId='abc123'
+     * );
      */
     async clone(url, path, branch, commitId, username, password) {
         await this.toolboxApi.gitCloneRepository(this.instance.id, {
@@ -53,12 +140,26 @@ class Git {
         });
     }
     /**
-     * Creates a new commit with staged changes
-     * @param {string} path - Repository path
-     * @param {string} message - Commit message
-     * @param {string} author - Author name
-     * @param {string} email - Author email
+     * Commits staged changes.
+     *
+     * This method creates a new commit with the staged changes. Make sure to stage
+     * changes using the add() method before committing.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @param {string} message - Commit message describing the changes
+     * @param {string} author - Name of the commit author
+     * @param {string} email - Email address of the commit author
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Stage and commit changes
+     * await git.add('/workspace/repo', ['README.md']);
+     * await git.commit(
+     *   '/workspace/repo',
+     *   'Update documentation',
+     *   'John Doe',
+     *   'john@example.com'
+     * );
      */
     async commit(path, message, author, email) {
         await this.toolboxApi.gitCommitChanges(this.instance.id, {
@@ -69,11 +170,27 @@ class Git {
         });
     }
     /**
-     * Pushes local commits to remote repository
-     * @param {string} path - Repository path
+     * Push local changes to the remote repository.
+     *
+     * This method pushes committed changes to the remote repository. If the remote
+     * requires authentication, username and password/token must be provided.
+     *
+     * @param {string} path - Absolute path to the Git repository root
      * @param {string} [username] - Git username for authentication
-     * @param {string} [password] - Git password/token for authentication
+     * @param {string} [password] - Git password or token for authentication
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Push to a public repository
+     * await git.push('/workspace/repo');
+     *
+     * @example
+     * // Push to a private repository
+     * await git.push(
+     *   '/workspace/repo',
+     *   'user',
+     *   'token'
+     * );
      */
     async push(path, username, password) {
         await this.toolboxApi.gitPushChanges(this.instance.id, {
@@ -83,11 +200,27 @@ class Git {
         });
     }
     /**
-     * Pulls changes from remote repository
-     * @param {string} path - Repository path
+     * Pulls changes from the remote repository.
+     *
+     * This method fetches and merges changes from the remote repository. If the remote
+     * requires authentication, username and password/token must be provided.
+     *
+     * @param {string} path - Absolute path to the Git repository root
      * @param {string} [username] - Git username for authentication
-     * @param {string} [password] - Git password/token for authentication
+     * @param {string} [password] - Git password or token for authentication
      * @returns {Promise<void>}
+     *
+     * @example
+     * // Pull from a public repository
+     * await git.pull('/workspace/repo');
+     *
+     * @example
+     * // Pull from a private repository
+     * await git.pull(
+     *   '/workspace/repo',
+     *   'user',
+     *   'token'
+     * );
      */
     async pull(path, username, password) {
         await this.toolboxApi.gitPullChanges(this.instance.id, {
@@ -97,9 +230,24 @@ class Git {
         });
     }
     /**
-     * Gets the current Git repository status
-     * @param {string} path - Repository path
-     * @returns {Promise<GitStatus>} Repository status information
+     * Gets the current status of the Git repository.
+     *
+     * This method returns information about the current state of the repository,
+     * including staged and unstaged changes, current branch, and untracked files.
+     *
+     * @param {string} path - Absolute path to the Git repository root
+     * @returns {Promise<GitStatus>} Current repository status including:
+     *                               - currentBranch: Name of the current branch
+     *                               - ahead: Number of commits ahead of the remote branch
+     *                               - behind: Number of commits behind the remote branch
+     *                               - branchPublished: Whether the branch has been published to the remote repository
+     *                               - fileStatus: List of file statuses
+     *
+     * @example
+     * const status = await workspace.git.status('/workspace/repo');
+     * console.log(`Current branch: ${status.currentBranch}`);
+     * console.log(`Commits ahead: ${status.ahead}`);
+     * console.log(`Commits behind: ${status.behind}`);
      */
     async status(path) {
         const response = await this.toolboxApi.gitGetStatus(this.instance.id, path);