Working with Merge in Git

In this week blog, I want to share my thought and experience after finishing my lab that is about working with git merge.

Git Merge Strategies

After completing a recent lab focused on working with Git, I gained a deeper understanding of the two primary merge strategies Git uses: Fast-forward and 3-way recursive (recursive-ort) merges.

• Fast-forward merge: This occurs when the main branch has no new commits since the feature branch was created. In this scenario, Git simply moves the main branch pointer forward to the latest commit from the feature branch. This type of merge does not create a separate merge commit, making it straightforward and linear.

• 3-way recursive merge: This approach is utilized when both the main branch and the feature branch have diverging commits. Git computes a common ancestor and attempts to merge the changes from both branches. Conflicts may arise if changes have been made to the same lines or files in both branches, requiring manual resolution. Initially, I was under the impression that conflicts would always occur when modifying the same file across different branches. However, conflicts only happen when the exact same line of code is changed in both branches.

Lab Implementation: Feature Branch Merges

For this lab, I worked on adding two features to my repository, VShell, which involved creating separate branches for each feature. These features were designed to improve the tool's functionality by supporting multiple input files/folders and streaming output.

Feature 1: Support Multiple Files and Folders - issue-15:

The first feature involved enabling the tool to process multiple files and folder paths simultaneously. Previously, the tool only handled individual file inputs, but with this enhancement, users can now pass multiple files or directories as arguments. All files within the directories are processed.

To implement this, I extended the existing logic to recursively iterate through folder contents, converting file paths to absolute paths, and storing all relevant files in an array. The relevant snippet:

files.forEach((file) => {
    // convert a file path to an absolute path
const filePath = path.resolve(file);
...
const directoryFiles = fs
          .readdirSync(filePath)
          .map((f) => path.join(filePath, f));
allFiles = allFiles.concat(directoryFiles);
...
const results = allFiles.map((file) => {
    process.stderr.write(`Debug: Processing file: ${file}. \n`);
    return fs.readFileSync(file, "utf-8");
});
return results.join("\n");
}

This code ensures that both individual files and all files within directories are processed accordingly.

Feature 2: Streaming Responses to Stdout - issue-16:

The second feature added streaming support to the tool, enabling real-time output of responses to stdout using the -s/--stream flag. This is a significant improvement over the previous implementation, where responses were only written to an output file or displayed in full once processing was complete.

To achieve this, I introduced asynchronous iteration using the for await...of loop to handle data chunks as they are streamed. Additionally, I tracked token usage in real-time, as token information is only available in the final response chunk. Here is the core logic:

if (options.stream) {
// Handle streaming response
const { response, tokenInfo } = await readStream(chatCompletion);
return { response, tokenInfo };
}

async function readStream(stream) {
  let response = "";
  let tokenInfo;
  for await (const chunk of stream) {
    const content = chunk.choices[0]?.delta?.content;
    if (content) {
      process.stdout.write(content);
      response += content;
    }
    // The last chunk will contain the usage information
    if (chunk?.x_groq?.usage) {
      // Retrieve Token Usage from Response
      const usage = chunk?.x_groq?.usage;
      const promptToken = usage?.prompt_tokens || 0;
      const completionToken = usage?.completion_tokens || 0;
      const totalToken = usage?.total_tokens || 0;
      tokenInfo = { promptToken, completionToken, totalToken };
    }
  }
  return { response, tokenInfo };
}

Notes:

The real-time streaming approach required adjustments in token tracking, as opposed to the simpler method used for non-streamed responses, where usage data can be accessed directly.

For streaming, the token usage object can only be accessed after processing the final chunk in the loop.

// The last chunk will contain the usage information
if (chunk?.x_groq?.usage) {
  // Retrieve Token Usage from Response
  const usage = chunk?.x_groq?.usage;
  ...
}

By default, when using the -s/--stream flag without specifying an output file via -o/--output, the response will be streamed and displayed in the console in real time. However, if the user wants to export the response to a file, they can specify the output file using the -o/--output flag.

Merge Process and Git Merge Strategy

After completing both features, I initiated the merge process, starting by merging Feature 1 into the main branch, followed by Feature 2. Since the features were developed in separate files, no conflicts occurred during the merge process. However, Git used the ORT merge strategy (Ostensibly Recursive's Twin), which is the default starting from Git 2.34. The ORT strategy is a rewrite of the classic recursive merge strategy, offering better performance and accuracy in handling complex merge scenarios.

My final merge commit hash was: 286e23c