@ibgib/vcs-gib 0.0.6

package/src/cli/commands/commit-log-cmd.respec.node.mts

@@ -0,0 +1,276 @@
+/**
+ * @module commit-log-cmd.respec
+ * 
+ * Unit tests for `vcs commit` and `vcs log` command handlers.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import {
+    respecfully, ifWe, iReckon
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { executeInitCmd } from './init-cmd.mjs';
+import { executeAddCmd } from './add-cmd.mjs';
+import { executeStatusCmd } from './status-cmd.mjs';
+import { executeCommitCmd } from './commit-cmd.mjs';
+import { executeLogCmd } from './log-cmd.mjs';
+import { executeBranchCmd } from './branch-cmd.mjs';
+import { executeCheckoutCmd } from './checkout-cmd.mjs';
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { getB2tFSIndexIbGib } from '../../engine/index/index-helper.mjs';
+
+const lc = `[apps/vcs-gib/src/cli/commands/commit-log-cmd.respec.node.mts]`;
+
+await respecfully(lc, `vcs commit and vcs log Command Handlers`, async () => {
+
+    await ifWe(lc, `rejects commit when no message is provided`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_1');
+        const vcsFolderName = '.vcsgib_test_commit_1';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            await fs.writeFile(path.join(testDir, 'file1.txt'), 'Hello Commit', 'utf8');
+            await executeAddCmd({
+                paths: ['file1.txt'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            let errorThrown = false;
+            try {
+                await executeCommitCmd({
+                    message: '',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                errorThrown = true;
+                iReckon(lc, err.message).includes('Commit message is required');
+            }
+
+            iReckon(lc, errorThrown).isGonnaBeTrue();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `rejects commit when no items are staged`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_2');
+        const vcsFolderName = '.vcsgib_test_commit_2';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            let errorThrown = false;
+            try {
+                await executeCommitCmd({
+                    message: 'Empty commit',
+                    targetDir: testDir,
+                    vcsFolderName,
+                    quiet: true,
+                });
+            } catch (err: any) {
+                errorThrown = true;
+                iReckon(lc, err.message).includes('Nothing to commit');
+            }
+
+            iReckon(lc, errorThrown).isGonnaBeTrue();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `commits staged files and advances active branch tip`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_3');
+        const vcsFolderName = '.vcsgib_test_commit_3';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            await fs.writeFile(path.join(testDir, 'hello.txt'), 'Hello ibgib repository!', 'utf8');
+            await executeAddCmd({
+                paths: ['hello.txt'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const { localSpace: spaceAdd, vcsPath: vcsPathAdd } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName,
+            });
+            const indexAdd = await getB2tFSIndexIbGib({ space: spaceAdd, vcsPath: vcsPathAdd });
+            iReckon(lc, Boolean(indexAdd?.data?.staged_item && indexAdd.data.staged_item.length > 0)).isGonnaBeTrue();
+            iReckon(lc, indexAdd?.rel8ns?.staged_item).isGonnaBeFalsy();
+
+            const commitRes = await executeCommitCmd({
+                message: 'Initial repository commit',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const { localSpace: spaceCommit, vcsPath: vcsPathCommit } = await bootstrapVcsMetaspace({
+                repoPath: testDir,
+                vcsFolderName,
+            });
+            const indexCommit = await getB2tFSIndexIbGib({ space: spaceCommit, vcsPath: vcsPathCommit });
+            iReckon(lc, indexCommit?.data?.staged_item).willEqual([]);
+            iReckon(lc, indexCommit?.rel8ns?.staged_item).isGonnaBeFalsy();
+
+            iReckon(lc, commitRes.branchName).willEqual('main');
+            iReckon(lc, commitRes.committedPaths).includes('hello.txt');
+            iReckon(lc, Boolean(commitRes.commitAddr)).isGonnaBeTrue();
+            iReckon(lc, Boolean(commitRes.commentAddr)).isGonnaBeTrue();
+
+            const statusRes = await executeStatusCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, statusRes.staged.length).willEqual(0);
+            iReckon(lc, statusRes.modified.length).willEqual(0);
+            iReckon(lc, statusRes.untracked.length).willEqual(0);
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `displays formatted commit history with executeLogCmd across multiple commits`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_4');
+        const vcsFolderName = '.vcsgib_test_commit_4';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Commit 1
+            await fs.writeFile(path.join(testDir, 'file1.txt'), 'Version 1', 'utf8');
+            await executeAddCmd({
+                paths: ['file1.txt'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'First commit message',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Commit 2
+            await fs.writeFile(path.join(testDir, 'file2.txt'), 'Version 2', 'utf8');
+            await executeAddCmd({
+                paths: ['file2.txt'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Second commit message',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const logRes = await executeLogCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, logRes.branchName).willEqual('main');
+            iReckon(lc, logRes.commits.length).willEqual(2);
+            iReckon(lc, logRes.commits[0].message).willEqual('Second commit message');
+            iReckon(lc, logRes.commits[1].message).willEqual('First commit message');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+
+    await ifWe(lc, `walks feature branch commits with executeLogCmd on active feature branch`, async () => {
+        const testDir = path.join(process.cwd(), '.test_commit_log_feature');
+        const vcsFolderName = '.vcsgib_test_commit_feature';
+        try {
+            await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Commit on main
+            await fs.writeFile(path.join(testDir, 'main.txt'), 'Main branch content', 'utf8');
+            await executeAddCmd({
+                paths: ['main.txt'],
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Main branch commit',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Create and checkout feature branch
+            await executeBranchCmd({
+                branchName: 'feature-log',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+            const checkoutRes = await executeCheckoutCmd({
+                branchName: 'feature-log',
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            // Commit on feature branch
+            await fs.writeFile(path.join(checkoutRes.worktreePath, 'feature.txt'), 'Feature branch content', 'utf8');
+            await executeAddCmd({
+                paths: ['feature.txt'],
+                targetDir: checkoutRes.worktreePath,
+                vcsFolderName,
+                quiet: true,
+            });
+            await executeCommitCmd({
+                message: 'Feature branch commit',
+                targetDir: checkoutRes.worktreePath,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            const logRes = await executeLogCmd({
+                targetDir: checkoutRes.worktreePath,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, logRes.branchName).willEqual('feature-log');
+            iReckon(lc, logRes.commits.length).willEqual(1);
+            iReckon(lc, logRes.commits[0].message).willEqual('Feature branch commit');
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+});

package/src/cli/commands/init-cmd.mts

@@ -0,0 +1,152 @@
+/**
+ * @module init-cmd
+ * 
+ * Command handler for `vcs init [targetDir]`.
+ * Initializes local repository space, root B2tFS folder item, default branch, and in-band space index.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg, getUUID } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { Factory_V1 } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { putInSpace, persistTransformResult } from '@ibgib/core-gib/dist/witness/space/space-helper.mjs';
+
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { getB2tFSItemIb } from '../../engine/item/item-atom-helper.mjs';
+import { B2tFSItemIbGib_V1 } from '../../engine/item/item-types.mjs';
+import { createB2tFSBranchIbGib, getB2tFSBranchSpaceName } from '../../engine/branch/branch-helper.mjs';
+import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
+import { createB2tFSIndexIbGib, writeVcsIndexProjection } from '../../engine/index/index-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[init-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface InitCmdOpts {
+    targetDir?: string;
+    vcsFolderName?: string;
+    defaultBranchName?: string;
+    quiet?: boolean;
+}
+
+export interface InitCmdResult {
+    vcsPath: string;
+    spaceId: string;
+    branchName: string;
+    rootItemIb: string;
+}
+
+export async function executeInitCmd({
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    defaultBranchName = 'main',
+    quiet = false,
+}: InitCmdOpts = {}): Promise<InitCmdResult> {
+    const lc = `${lcFile}[${executeInitCmd.name}]`;
+    try {
+        if (logalot) {
+            console.log(`${lc} starting... (I: 8a9b10c11d12e13f14a15b16c17d18e1)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+        const vcsPath = path.join(absTargetDir, vcsFolderName);
+
+        // Create target repository folder if it doesn't exist
+        await fs.mkdir(absTargetDir, { recursive: true });
+
+        // Bootstrap Metaspace
+        const { metaspace } = await bootstrapVcsMetaspace({
+            repoPath: absTargetDir,
+            vcsFolderName,
+            defaultSpaceName: `vcs_${path.basename(absTargetDir).replace(/[^a-zA-Z0-9_\-]/g, '_')}`,
+        });
+
+        // Initialize b2s_main branch space
+        const { space: branchSpace, spaceId } = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName: defaultBranchName,
+        });
+
+        const folderName = path.basename(absTargetDir) || 'root';
+        const rootNameHash = await getUUID();
+
+        // 1. Create root folder B2tFS item inside b2s_main space
+        const rootItemRes = await Factory_V1.firstGen({
+            parentIbGib: ROOT,
+            ib: getB2tFSItemIb('folder', folderName, rootNameHash),
+            data: {
+                name: folderName,
+                nameHash: rootNameHash,
+                fsType: 'folder',
+                diffTransactionId: await getUUID(),
+                uuid: await getUUID(),
+                classname: 'B2tFSItemIbGib_V1',
+            },
+        });
+
+        const rootItem = rootItemRes.newIbGib as B2tFSItemIbGib_V1;
+        await persistTransformResult({ resTransform: rootItemRes, space: branchSpace });
+        await metaspace.registerNewIbGib({ ibGib: rootItem, space: branchSpace });
+
+        // 2. Create default branch pointing to root folder inside b2s_main space
+        const branchIbGib = await createB2tFSBranchIbGib({
+            branchName: defaultBranchName,
+            rootItem,
+            space: branchSpace,
+            metaspace,
+        });
+        const branchAddr = getIbGibAddr({ ibGib: branchIbGib });
+
+        // 3. Create space index meta object stored inside b2s_main space
+        const indexIbGib = await createB2tFSIndexIbGib({
+            spaceId,
+            activeSpaceId: getB2tFSBranchSpaceName(defaultBranchName),
+            activeBranch: defaultBranchName,
+            space: branchSpace,
+            metaspace,
+            branchAddr,
+        });
+
+        // 4. Write read-only projection file in .vcsgib/
+        await writeVcsIndexProjection({
+            vcsPath,
+            indexIbGib,
+        });
+
+        // Clean up legacy out-of-band state files if present
+        try {
+            await fs.rm(path.join(vcsPath, 'vcs_state.json'), { force: true });
+        } catch {
+            // Ignore if missing
+        }
+        try {
+            await fs.rm(path.join(vcsPath, 'staging.json'), { force: true });
+        } catch {
+            // Ignore if missing
+        }
+
+        if (!quiet) {
+            console.log(`Initialized empty ibgib repository in ${vcsPath} (I: 6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f)`);
+            console.log(`  Branch: ${defaultBranchName}`);
+            console.log(`  Root Item: ${rootItem.ib}`);
+        }
+
+        return {
+            vcsPath,
+            spaceId,
+            branchName: defaultBranchName,
+            rootItemIb: rootItem.ib,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 9b10c11d12e13f14a15b16c17d18e19f)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d)`);
+        }
+    }
+}

package/src/cli/commands/init-cmd.respec.node.mts

@@ -0,0 +1,49 @@
+/**
+ * @module init-cmd.respec
+ * 
+ * Unit tests for `vcs init` command handler.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+
+import {
+    respecfully, ifWe, iReckon
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+
+import { executeInitCmd } from './init-cmd.mjs';
+
+const lc = `[apps/vcs-gib/src/cli/commands/init-cmd.respec.node.mts]`;
+
+await respecfully(lc, `vcs init Command Handler`, async () => {
+
+    await ifWe(lc, `initializes repository space, branch, and index in target folder`, async () => {
+        const testDir = path.join(process.cwd(), '.test_init_repo');
+        const vcsFolderName = '.vcsgib_init_test';
+        try {
+            const res = await executeInitCmd({
+                targetDir: testDir,
+                vcsFolderName,
+                quiet: true,
+            });
+
+            iReckon(lc, res.branchName).willEqual('main');
+            iReckon(lc, res.rootItemIb).includes('b2tfs_item folder');
+            iReckon(lc, res.vcsPath).includes(vcsFolderName);
+
+            // Strict Repository Location Isolation Assertions:
+            // 1. Storage MUST be inside vcsPath (.vcsgib_init_test)
+            const ibgibInsideVcsFolder = existsSync(path.join(res.vcsPath, 'ibgib')) || existsSync(path.join(res.vcsPath, 'space'));
+            iReckon(lc, ibgibInsideVcsFolder).isGonnaBeTrue();
+
+            // 2. Storage MUST NOT spill into testDir root or process.cwd() as stray 'ibgib' folder
+            const strayInTestDir = existsSync(path.join(testDir, 'ibgib'));
+            const strayInCwd = existsSync(path.join(process.cwd(), 'ibgib'));
+            iReckon(lc, strayInTestDir).isGonnaBeFalse();
+            iReckon(lc, strayInCwd).isGonnaBeFalse();
+        } finally {
+            await fs.rm(testDir, { recursive: true, force: true });
+        }
+    });
+});

package/src/cli/commands/log-cmd.mts

@@ -0,0 +1,197 @@
+/**
+ * @module log-cmd
+ * 
+ * Command handler for `vcs log`.
+ * Reads active branch timeline from B2tFSIndexIbGib_V1 in localSpace,
+ * walks branch timeline history backward, and displays formatted commit history.
+ */
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { getIbGibAddr } from '@ibgib/ts-gib/dist/helper.mjs';
+import { getIbGibsFromCache_fallbackToSpaces } from '@ibgib/core-gib/dist/common/other/ibgib-helper.mjs';
+import { CommentIbGib_V1 } from '@ibgib/core-gib/dist/common/comment/comment-types.mjs';
+
+import { bootstrapVcsMetaspace } from '../../bootstrap/node-bootstrap.mjs';
+import { getOrCreateBranchSpace } from '../../engine/branch/branch-space-helper.mjs';
+import { getIbGibWithMetaspaceFallback } from '../../engine/item/item-helper.mjs';
+import { B2tFSBranchIbGib_V1 } from '../../engine/branch/branch-types.mjs';
+import { getB2tFSIndexIbGib, extractBranchNameFromAddr } from '../../engine/index/index-helper.mjs';
+import { GLOBAL_LOG_A_LOT } from '../../vcs-gib-constants.mjs';
+
+const lcFile = `[log-cmd]`;
+const logalot = GLOBAL_LOG_A_LOT;
+
+export interface VcsLogItem {
+    branchAddr: string;
+    commitAddr: string;
+    commentAddr?: string;
+    message: string;
+    timestamp: string;
+    author: string;
+    rootItemAddr?: string;
+}
+
+export interface LogCmdOpts {
+    targetDir?: string;
+    vcsFolderName?: string;
+    quiet?: boolean;
+}
+
+export interface LogCmdResult {
+    branchName: string;
+    commits: VcsLogItem[];
+}
+
+export async function executeLogCmd({
+    targetDir = process.cwd(),
+    vcsFolderName = '.vcsgib',
+    quiet = false,
+}: LogCmdOpts = {}): Promise<LogCmdResult> {
+    const lc = `${lcFile}[${executeLogCmd.name}]`;
+
+    try {
+        if (logalot) {
+            console.log(`${lc} starting executeLogCmd (I: 1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e)`);
+        }
+
+        const absTargetDir = path.resolve(targetDir);
+
+        const { metaspace, localSpace, vcsPath, repoRoot } = await bootstrapVcsMetaspace({
+            repoPath: absTargetDir,
+            vcsFolderName,
+        });
+
+        // Verify repo exists
+        try {
+            await fs.access(vcsPath);
+        } catch {
+            throw new Error(`Not an ibgib repository (directory ${vcsPath} does not exist) (E: 2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f)`);
+        }
+
+        // 1. Fetch authoritative B2tFSIndexIbGib_V1 directly from localSpace
+        const indexIbGib = await getB2tFSIndexIbGib({ space: localSpace, vcsPath });
+        if (!indexIbGib) {
+            throw new Error(`Repository index B2tFSIndexIbGib_V1 not found in localSpace (E: 3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a)`);
+        }
+
+        const branchName = indexIbGib.data?.activeBranch || 'main';
+
+        // Target active branch space b2s_<activeBranch>
+        const { space: activeSpace } = await getOrCreateBranchSpace({
+            metaspace,
+            vcsPath,
+            branchName,
+        });
+
+        // 2. Fetch active branch node address matching active branchName
+        const branchAddrs = [
+            ...(indexIbGib.rel8ns?.branch || []),
+            ...(indexIbGib.rel8ns?.branch_tjp || []),
+        ];
+
+        let currBranchAddr: string | undefined;
+
+        // Match branchName against branchAddrs by space-qualified address or raw atom ib string
+        for (const addr of branchAddrs) {
+            const parsedName = extractBranchNameFromAddr(addr);
+            if (parsedName === branchName) {
+                currBranchAddr = addr;
+                break;
+            }
+        }
+
+        // Fallback: fetch branch nodes via getIbGibWithMetaspaceFallback to match b.data?.name === branchName
+        if (!currBranchAddr) {
+            for (const addr of branchAddrs) {
+                const bIbGib = await getIbGibWithMetaspaceFallback({
+                    addr,
+                    space: activeSpace,
+                    metaspace,
+                }) as B2tFSBranchIbGib_V1;
+                if (bIbGib?.data?.name === branchName) {
+                    currBranchAddr = addr;
+                    break;
+                }
+            }
+        }
+
+        // Ultimate fallback if no match found
+        if (!currBranchAddr) {
+            currBranchAddr = branchAddrs.at(0);
+        }
+        const visitedAddrs = new Set<string>();
+        const commits: VcsLogItem[] = [];
+
+        // 3. Walk timeline history backward
+        while (currBranchAddr && !visitedAddrs.has(currBranchAddr)) {
+            visitedAddrs.add(currBranchAddr);
+
+            const branchIbGib = await getIbGibWithMetaspaceFallback({
+                addr: currBranchAddr,
+                space: activeSpace,
+                metaspace,
+            }) as B2tFSBranchIbGib_V1;
+
+            if (!branchIbGib) {
+                break;
+            }
+
+            const commentAddr = branchIbGib.rel8ns?.comment?.at(0);
+            const rootItemAddr = branchIbGib.rel8ns?.b2tfs_item?.at(0);
+
+            if (commentAddr) {
+                const commentIbGib = await getIbGibWithMetaspaceFallback({
+                    addr: commentAddr,
+                    space: activeSpace,
+                    metaspace,
+                }) as CommentIbGib_V1;
+
+                const message = commentIbGib?.data?.text || '';
+                const timestamp = commentIbGib?.data?.textTimestamp || commentIbGib?.data?.timestamp || branchIbGib.data?.committedAt || '';
+                const author = 'vcs-user';
+
+                commits.push({
+                    branchAddr: currBranchAddr,
+                    commitAddr: commentAddr,
+                    commentAddr,
+                    message,
+                    timestamp,
+                    author,
+                    rootItemAddr,
+                });
+            }
+
+            // Move to previous branch node in timeline
+            currBranchAddr = branchIbGib.rel8ns?.past?.at(0) || branchIbGib.rel8ns?.ancestor?.at(0);
+        }
+
+        if (!quiet) {
+            console.log(`Branch: ${branchName} (I: 4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b)`);
+            if (commits.length === 0) {
+                console.log('No commits yet.');
+            } else {
+                for (const commit of commits) {
+                    console.log(`\ncommit ${commit.commitAddr}`);
+                    console.log(`Author: ${commit.author}`);
+                    console.log(`Date:   ${commit.timestamp}`);
+                    console.log(`\n    ${commit.message}\n`);
+                }
+            }
+        }
+
+        return {
+            branchName,
+            commits,
+        };
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)} (E: 5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c)`);
+        throw error;
+    } finally {
+        if (logalot) {
+            console.log(`${lc} complete. (I: 6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d)`);
+        }
+    }
+}