From 10 Lines to 100 Retries: Building a Git Clone Function That Doesn't Quit

The Evolution of a Clone Function: A Journey in Developer Experience

As developers, we spend a significant portion of our day performing repetitive tasks. One of the most common? Cloning repositories. While git clone works perfectly fine, there's always room to improve our workflows. This article chronicles the evolution of a custom clone function—a shell utility that started simple and grew more sophisticated as real-world needs emerged.

This isn't just a story about shell scripting. It's a case study in iterative development, user experience design, and the engineering mindset of continuously improving our tools.

The Problem Space

Before we dive into the code, let's understand the problem. When working with GitHub repositories, developers typically:

1. Copy a repository URL from GitHub
2. Open their terminal
3. Run git clone <url>
4. Manually cd into the newly created directory

This workflow has friction points:

• Context switching: Copying URLs, switching between browser and terminal
• Manual navigation: Always having to cd into the directory
• URL verbosity: Full URLs are long and cumbersome
• Collision handling: What happens when the directory already exists?
• Branch management: Cloning specific branches requires extra steps

Our custom clone function aims to smooth out these rough edges.

Version 1: The Simplest Thing That Could Work

function clone() {
  if [[ -z $2 ]]; then
    gh repo clone "$1" && cd "$(basename "$1" .git)" || echo "Failed to navigate to the directory"
  else
    gh repo clone "$1" "$2" && cd "$2" || echo "Failed to navigate to the directory"
  fi
}

The Core Idea: Use GitHub CLI (gh) instead of raw git, clone the repo, and automatically cd into it.

What This Solved:

• Eliminated the manual cd step
• Used gh CLI for better GitHub integration (handles authentication seamlessly)
• Supported custom directory names via an optional second parameter

Limitations:

• Only worked with full URLs or gh-compatible formats
• No handling for existing directories
• Limited flexibility in URL formats

Key Lesson: Start with the 80% Use Case

This first version solved the most common workflow. It wasn't perfect, but it worked for the majority of daily cloning tasks. This is a critical principle in tool development—ship something useful quickly, then iterate based on actual pain points.

Version 2: Making URLs Flexible

function clone() {
  if [[ $1 == *"/"* && $1 != http* && $1 != git@* ]]; then
    repo_url="https://github.com/$1.git"
  else
    repo_url="$1"
  fi

  if [[ -z $2 ]]; then
    git clone "$repo_url" && cd "$(basename "$repo_url" .git)"
  else
    git clone "$repo_url" "$2" && cd "$2"
  fi
}

The Evolution: Added support for shorthand notation. Now you could type clone user/repo instead of pasting a full URL.

What This Solved:

• Dramatically reduced typing for the most common case (cloning from GitHub)
• Made the tool feel more like a native CLI command
• Reduced cognitive load—just remember "user/repo"

The Trade-off: We switched from gh repo clone to git clone, which meant we needed to handle authentication differently. This shows how each iteration brings new considerations.

Key Lesson: Developer Experience is About Removing Cognitive Load

The shorthand notation (user/repo) became the primary interface. Why? Because it matched the mental model developers already had. When you see a GitHub repo, you think "facebook/react", not "https://github.com/facebook/react.git". Good DX aligns with existing mental models.

Version 3: Handling the Real World (Collisions)

function clone() {
  # ... URL parsing logic ...

  if gh clone "$repo_url" "$target_dir"; then
    cd "$target_dir"
  else
    echo "Initial clone failed, retrying with alternate folder name..."
    fallback_dir="${repo_name}_${github_user}"
    if gh clone "$repo_url" "$fallback_dir"; then
      cd "$fallback_dir"
    else
      echo "Clone failed again. Exiting."
    fi
  fi
}

The Evolution: Added retry logic with alternate folder names when the target directory already exists.

What This Solved:

• Eliminated the frustrating "directory already exists" error
• Allowed multiple clones of the same repo (useful for testing different branches)
• Removed the need to manually pick a different name

The Pattern: repo-name_username became the fallback naming scheme, making it easy to identify whose fork you're working with.

Key Lesson: Graceful Degradation in Tooling

When the ideal path fails, good tools don't just error out—they try alternatives. This retry logic transformed a frustrating error into a seamless experience. The function now handles the common case (unique name) and the edge case (collision) without user intervention.

Version 4: Multiple Retries and Better User Extraction

function clone() {
  # ... URL parsing to extract github_user and repo_name ...

  target_dir="${2:-$repo_name}"

  if gh repo clone "$repo_url" "$target_dir"; then
    cd "$target_dir"
  else
    lowercase_github_user=$(echo "$github_user" | tr '[:upper:]' '[:lower:]')
    base_dir="${repo_name}_${lowercase_github_user}"
    retry_count=1
    max_retries=100

    while [[ $retry_count -le $max_retries ]]; do
      fallback_dir="${base_dir}_$retry_count"
      if gh repo clone "$repo_url" "$fallback_dir"; then
        cd "$fallback_dir"
        return 0
      fi
      ((retry_count++))
    done

    echo "Clone failed after $max_retries attempts."
    return 1
  fi
}

The Evolution: Enhanced the retry mechanism to try up to 100 different directory names.

What This Solved:

• Handles scenarios where you've cloned the same repo multiple times
• Uses a predictable numbering scheme (repo_user_1, repo_user_2, etc.)
• Properly extracts username from different URL formats (HTTPS, SSH)

The Engineering Decision: Why 100 retries? It's effectively unlimited for practical purposes while still having a safety bound. This prevents infinite loops if something is fundamentally wrong.

Key Lesson: Defensive Programming and Edge Cases

By this point, the function handles:

• Different URL formats (HTTPS, SSH, shorthand)
• Case sensitivity in usernames
• Multiple collisions with sequential numbering
• Proper error codes (return 1)

Each iteration added more "defensive" code—code that anticipates and handles edge cases gracefully.

Version 5: Branch Support

function clone() {
  # Regex to detect branch in URL: github.com/user/repo/tree/branch
  if [[ "$input_url" =~ github\.com/([^/]+)/([^/]+)/tree/(.+) ]]; then
    github_user="${BASH_REMATCH[1]}"
    repo_name="${BASH_REMATCH[2]}"
    branch="${BASH_REMATCH[3]}"
    repo_url="https://github.com/$github_user/$repo_name.git"
  fi

  # ... clone logic ...

  if [[ -n "$branch" ]]; then
    git fetch origin "$branch"
    git checkout "$branch"
  fi
}

The Evolution: Parse branch information from GitHub URLs and automatically check out that branch after cloning.

What This Solved:

• Eliminated the copy URL → clone → checkout branch workflow
• Allowed direct linking to specific branches from browser to terminal
• Matched the natural workflow of browsing code on GitHub

The UX Win: You can now copy a URL from your browser (which might include /tree/feature-branch) and paste it directly. The function intelligently extracts and checks out that branch.

Key Lesson: Meet Users Where They Are

This feature emerged from observing actual behavior: developers often review code on GitHub's web interface on a specific branch, then want to clone that exact branch. By supporting GitHub's URL structure directly, we eliminated mental overhead and manual steps.

Version 6: Comprehensive URL Parsing and Debugging

The final version includes:

function clone() {
  # Comprehensive regex patterns for:
  # - Full HTTPS URLs with branches
  # - Full HTTPS URLs without branches
  # - SSH URLs
  # - Shorthand notation

  # Extensive debug logging
  echo "DEBUG: Input URL: '$input_url'"
  echo "DEBUG: Extracted GitHub User: '$github_user'"
  echo "DEBUG: Extracted Repo Name: '$repo_name'"

  # ... rest of implementation ...
}

The Evolution: Added comprehensive URL format support and debug logging.

What This Solved:

• Handles virtually any way someone might reference a GitHub repo
• Provides visibility into what the function is doing (crucial for debugging)
• Makes the tool maintainable and debuggable

The Engineering Maturity: Debug logging might seem simple, but it's often the difference between a tool you trust and one you don't. When things go wrong (and they will), debug output helps you understand why.

Key Lesson: Observability in Developer Tools

Production-grade tools need observability. Even for a shell function, adding debug output transforms troubleshooting from "I don't know why this isn't working" to "I can see exactly where it's failing." This is the same principle that drives logging, monitoring, and tracing in production systems.

The Architecture of the Final Version

Let's break down the final implementation's key components:

1. Input Recognition (The Parser)

# Case 1: Full URL with branch
if [[ "$input_url" =~ ^https?://github\.com/([^/]+)/([^/]+)/tree/(.+)$ ]]; then
  # Extract user, repo, branch

# Case 2: Full HTTPS URL
elif [[ "$input_url" =~ ^https?://github\.com/([^/]+)/([^/]+)(\.git)?$ ]]; then
  # Extract user, repo

# Case 3: SSH URL
elif [[ "$input_url" =~ ^git@github\.com:([^/]+)/([^/]+)(\.git)?$ ]]; then
  # Extract user, repo

# Case 4: Shorthand
elif [[ "$input_url" =~ ^([^/]+)/([^/]+)$ ]]; then
  # Extract user, repo
fi

This pattern matching is the foundation. It normalizes wildly different input formats into a consistent internal representation.

2. Clone Strategy (The Executor)

if gh repo clone "$gh_clone_url" "$target_dir"; then
  # Success path
else
  # Fallback path with numbered retries
fi

The function tries the ideal case first, then gracefully degrades to numbered alternatives. This is a critical pattern in resilient systems.

3. Post-Clone Actions (The Finalizer)

cd "$target_dir"
if [[ -n "$branch" ]]; then
  git fetch origin "$branch"
  git checkout "$branch"
fi

The function doesn't just clone—it leaves you in the right place, on the right branch, ready to work.

Engineering Principles Demonstrated

Looking back at this evolution, several software engineering principles emerge:

1. Iterative Development

Each version solved a specific problem encountered in real use. We didn't try to build the perfect solution upfront—we evolved it based on actual needs.

2. User-Centered Design

Every improvement came from observing actual developer workflows(my workflow here) and removing friction points. The best tools are invisible—they just work the way you think they should.

3. Defensive Programming

The function handles edge cases, provides fallbacks, and fails gracefully. It doesn't assume the happy path will always succeed.

4. Maintainability

Debug logging and clear error messages make the tool maintainable. Future me (or other developers) can understand what's happening and why.

5. Consistent Abstraction

Despite growing more complex, the interface remained simple: clone <repo>. Internal complexity grew, but the user-facing API stayed clean.

Practical Takeaways for Engineers

Start Simple, Iterate Based on Real Use

Don't build for hypothetical use cases. Ship something minimal, use it daily, and let actual pain points drive your improvements.

Good DX is About Removing Steps

Every version of this function removed manual steps from the workflow. Count the steps in your current process—each one is an opportunity for improvement.

Error Handling is a Feature

The retry logic with numbered fallbacks isn't just error handling—it's a user experience feature. It transforms "error: directory exists" into seamless operation.

Patterns Over Documentation

The repo_user_1, repo_user_2 naming pattern is self-documenting. Users can immediately understand what happened without reading a manual.

Observability Matters at Every Scale

Debug output in a shell function follows the same principle as distributed tracing in microservices: visibility into what's happening enables better debugging and builds trust.

Conclusion: The Mindset of Continuous Improvement

This clone function's evolution demonstrates a mindset every engineer should cultivate: your tools are never "done." They're living artifacts that should evolve alongside your needs and understanding.

The journey from a simple wrapper to a sophisticated developer tool mirrors how we should approach all software development:

1. Solve the immediate problem (V1: just clone and cd)
2. Remove friction (V2: support shorthand)
3. Handle reality (V3-4: deal with collisions)
4. Anticipate workflow (V5: support branches)
5. Build for maintainability (V6: add debugging)

Whether you're building a shell function, a frontend component, or a distributed system, these principles apply. Start simple, observe actual usage, iterate based on real pain points, and always leave the codebase better than you found it.

The best developer tools feel like magic because they handle complexity invisibly. They meet you where you are, understand your intent, and just work. That's the standard we should hold all our code to—whether it's a 20-line shell function or a 20,000-line application.

P.S - All the functions look like JavaScript functions.

---

What small tools have you built that evolved over time? What patterns emerged in your iterations? The most impactful improvements often come from scratching your own itches and paying attention to the tiny friction points in your daily workflow.

Original post was posted on my personal website, here is the link to it

.