gitx

Basics

Mon, 01 Jan 0001 00:00:00 +0000

Installing gitx

Mon, 01 Jan 0001 00:00:00 +0000

Installation Script

The easiest way to install gitx is by using the installation script. Open your terminal and run the following command:

curl -sSL https://raw.githubusercontent.com/gitxtui/gitx/master/install.sh | bash

This script will automatically detect your operating system and architecture, download the latest release of gitx, and install it to /usr/local/bin.

Using go install

Requires go to be installed on your system:

go install github.com/gitxtui/gitx/cmd/gitx@latest

This will download the correct binary according to your operating system and place it at ~/go/bin/gitx.

Introduction to Git

Mon, 01 Jan 0001 00:00:00 +0000

Git is an open source, distributed version control system (VCS) that helps you track changes in your code and collaborate with others efficiently.

Imagine you’re writing a book. You make changes every day—sometimes adding new chapters, sometimes fixing typos. After a few weeks, you wonder: What if I want to see the old draft? What if two people are editing the same chapter?

This is where Git comes in.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

What is it?

gitx is a Terminal User Interface (TUI) helper designed to simplify the process of learning and using Git, the most widely used version control system (VCS). Instead of typing long and often confusing commands, gitx presents a more guided and interactive interface that helps beginners understand Git concepts while still working inside the terminal. It is especially useful for students, new developers, or anyone who wants to strengthen their Git fundamentals by not only providing an easy access to all the git functions but also educating about doing all the said exercises manually.

Project Roadmap

Mon, 01 Jan 0001 00:00:00 +0000

✅ Completed Done

Basic TUI Structure: A foundational terminal user interface is in place, providing the core layout and panel management for the application.
Git Command Mapping: Essential Git commands are integrated into the TUI, allowing users to perform basic operations visually.
Theme Generation: The application can generate themes from a predefined set of color palettes, allowing for initial UI customization.
Custom Theme Support: Implement a system for users to add their own themes via configuration files in the .config directory.
Expanded Git Command Support: Integrate a wider range of Git commands to provide more comprehensive repository management capabilities.
Bug Fixes: Address any outstanding bugs to improve stability and reliability.
Command History and Logging: Allow the secondary panel to store all the git commands history and gitx logs.
Repository Initialization: Add a feature that allows users to initialize a new Git repository in the current directory if one doesn't already exist.
Safety Warnings: Implement a warning system to alert users when they are about to initialize a repository in a potentially problematic location.
Custom Keybindings: Update config.toml logic to allow users to remap keys (currently hardcoded in keys.go).

🚀 In Progress Active

Items will be moved here soon from the planned section

📋 Planned Upcoming

Improved Visual Diff Viewer: Enhance the diff viewer to provide a more intuitive and detailed representation of changes.
Interactive Staging: Allow users to stage and unstage individual lines or hunks of code directly from the visual diff viewer.
Merge Conflict Resolver: Build a tool to help users resolve merge conflicts from within the TUI.

Getting started with GIT

Mon, 01 Jan 0001 00:00:00 +0000

1. Installation

You only need to install Git once.

Windows: Download from GIT and install.
Mac:
```
brew install git
```

Linux (Ubuntu/Debian):

sudo apt update && sudo apt install git

ArchLinux

sudo pacman -Syu && sudo pacman -S git

Check if it’s installed:

git --version

2. The Git Workflow (The Big Picture)

Before typing anything, let’s understand how Git thinks.

Every project has:

Working Directory → where you edit files.

Keybinds

Mon, 01 Jan 0001 00:00:00 +0000

Overview

gitx is a keyboard-driven application with customizable keybindings. Every action in gitx can be remapped to your preferred key combination. This guide covers all available keybinds, how to customize them, and best practices for configuring your keyboard shortcuts.

Configuration

Keybindings are configured in your gitx configuration file located at ~/.config/gitx/config.toml. The keybindings section uses the following format:

[keybindings]
action_name = "key_combination"

Key Specification Format

Keys can be specified in several ways:

Custom Themes

Mon, 01 Jan 0001 00:00:00 +0000

Overview

gitx comes with built-in themes and supports fully customizable user-defined themes. You can modify colors, styles, and the overall appearance of the interface. This guide covers using built-in themes and creating your own custom themes.

Built-in Themes

gitx includes the following built-in themes:

GitHub Dark (default) - A clean dark theme based on GitHub’s color palette
Gruvbox - A retro groove color scheme

Using Built-in Themes

To switch between built-in themes:

The Three Stages in Git

Mon, 01 Jan 0001 00:00:00 +0000

What Are the Three Stages in Git?

Git tracks your changes in three main stages:
Working Directory, Staging Area (Index), and Repository (Commit History).
Understanding these stages is key to mastering Git’s workflow!

1. Working Directory

This is your project folder on your computer.
Any changes you make to files—editing, adding, deleting—happen here first.
Files in the working directory can be:
- Untracked: New files Git hasn’t seen before.
- Modified: Files you’ve changed since the last commit.

Example:
You edit main.py and add a new file README.md.
Both are in your working directory.

Stashing Changes in Git

Mon, 01 Jan 0001 00:00:00 +0000

What is Stashing?

Stashing in Git lets you temporarily save changes in your working directory that you’re not ready to commit.
It’s like putting your unfinished work in a “drawer” so you can switch branches, pull updates, or do other tasks—then come back and finish later.

Why Use Stash?

Switch branches safely:
If you have uncommitted changes but need to switch to another branch, stash lets you save your work without committing.
Keep your work-in-progress separate:
Avoid cluttering your commit history with incomplete or experimental changes.
Handle emergencies:
If you need to quickly fix something elsewhere, stash your current work and come back to it later.

How Does Stash Work?

When you run git stash, Git saves your changes (tracked files, and optionally untracked files) in a special stack.
Your working directory is then clean, as if you just checked out the branch.

Working with Branches

Mon, 01 Jan 0001 00:00:00 +0000

Listing Branches

To see your local branches, use:

git branch

Expected output:
* main

To list all branches (including remote branches), use:

git branch -a

Expected output:
* main
 remotes/origin/main

To list Remote branches (including remote branches), use:

git branch -r

Expected output:
* remotes/origin/main

The branch marked with an asterisk (*) is your currently active branch.
Any changes or commits you make are added to this branch.

Tip:
Use branches to keep your work organized and your main branch stable!

Creating Branches

Mon, 01 Jan 0001 00:00:00 +0000

Creating a Branch

Command 1: Create only

git branch <branch-name>

Creates a new branch.
Does not switch to it.
You’re still on the same branch as before.

Command 2: Create + switch

git checkout -b <branch-name>

Shortcut: creates the branch and switches to it.
Older syntax.

Command 3: Modern way

git switch -c <branch-name>

Recommended modern syntax.
Does the same thing as checkout -b.

Working with Remotes

Mon, 01 Jan 0001 00:00:00 +0000

Up until now, we have been working on our local system. Git, however, is built to facilitate collaboration among multiple developers. To let other developers work on our code, we need to publish this code to a website.

You can upload your code anywhere—zip it up and put it on cloud storage like Google Drive or Dropbox, or send the files as an attachment to your friend.
But these methods won’t preserve your commit history, branches, or collaboration features (unless you include the hidden .git folder, which is risky and not recommended).

Best Practices for Using Git

Mon, 01 Jan 0001 00:00:00 +0000

Following best practices helps you avoid mistakes, keep your project history clean, and collaborate smoothly with others.
Here are essential tips for working with Git, whether you’re solo or on a team!

1. Commit Often, But Meaningfully

Make small, focused commits:
Each commit should represent a single logical change.
Avoid huge commits:
Large commits are hard to review and revert.
Commit early and often:
This makes it easier to track changes and fix mistakes.

2. Write Clear Commit Messages

Describe what and why:
Explain what changed and why, not just “fix” or “update”.
Use the imperative mood:
Example: “Add login feature” instead of “Added login feature”.
Reference issues or tickets:
If using issue tracking, include references (e.g., Fixes #42).

3. Use Branches for Features and Fixes

Create a new branch for each feature or bugfix:
Keeps work isolated and makes merging easier.
Name branches descriptively:
Examples: feature/login, bugfix/header, hotfix/payment-crash.

4. Pull and Merge Regularly

Sync with the remote often:
Use git pull to get the latest changes before starting new work.
Resolve conflicts early:
The longer you wait, the harder conflicts become to fix.

5. Review Before You Commit

Check your changes:
Use git status and git diff to review what you’re about to commit.
Don’t commit secrets or sensitive data:
Double-check for passwords, API keys, or private info.

6. Clean Up Branches

Delete branches after merging:
Keeps your repository tidy and avoids confusion.
Remove stale or unused branches regularly.

7. Use .gitignore

Ignore files that shouldn’t be tracked:
Add build artifacts, logs, and environment files to .gitignore.
Keep .gitignore up to date as your project grows.

8. Protect Important Branches

Enable branch protection rules:
Prevent force-pushes, require pull requests, and enforce code reviews on critical branches like main or master.

9. Test Before You Push

Run tests and build your code before pushing:
Avoid breaking the shared codebase.

10. Document Your Workflow

Write down your team’s Git workflow:
Make sure everyone knows how to branch, merge, and review code.
Update documentation as your process evolves.

Summary Table

Practice	Why It Matters
Small, focused commits	Easier to review, revert, and understand
Clear commit messages	Helps everyone know what changed and why
Feature/fix branches	Isolate work, simplify collaboration
Pull/merge regularly	Avoid big conflicts, stay up to date
Review before commit	Prevent mistakes, keep history clean
Clean up branches	Tidy repo, avoid confusion
Use .gitignore	Don’t track unnecessary files
Protect branches	Keep important code safe
Test before push	Prevent breaking the build
Document workflow	Team clarity, fewer mistakes

Tip:
Good Git habits save time, prevent headaches, and make you a better collaborator.
Practice these tips and share them with your team!

Understanding HEAD

Mon, 01 Jan 0001 00:00:00 +0000

What is HEAD in Git?

When working with Git, you’ll often hear about something called HEAD.
Think of HEAD as a special pointer that tells Git, “This is where you are right now.”

HEAD: Your Current Position

HEAD always points to your current branch.
That branch, in turn, points to a specific commit (a snapshot of your project).

Visualization:

HEAD
 ↓
branch (e.g. main)
 ↓
commit (e.g. a1b2c3d)

When you make a new commit, the branch moves forward, and so does HEAD.

How HEAD Moves

If you switch branches, HEAD moves to point to the new branch.
If you make a commit, HEAD (via the branch) points to the new commit.

Detached HEAD State

Sometimes, HEAD doesn’t point to a branch, but directly to a commit.
This is called a detached HEAD.

Merging Branches

Mon, 01 Jan 0001 00:00:00 +0000

What is Merging?

Merging in Git is the process of taking the changes from one branch and combining them into another branch.
This is how you bring together work from different branches—like adding a new feature you built on a separate branch back into your main project.

Why Merge?

You might have a main branch that holds your stable code.
You create a feature branch to work on something new, so your main code isn’t disturbed.
When your feature is ready, you want to add it back to main—without losing any work from either branch.
Merging lets you combine the work from both branches, keeping all the commit history and changes.

How Does Merging Work?

When you merge, Git tries to automatically combine the changes from both branches.
If the changes don’t overlap, Git merges them automatically.
If the same lines were changed in both branches, you’ll get a merge conflict (see the Conflicts topic).

Handling Merge Conflicts

Mon, 01 Jan 0001 00:00:00 +0000

What is a Merge Conflict?

A merge conflict happens when Git cannot automatically combine changes from two branches.
This usually occurs when two branches have changed the same part of a file, or when one branch deletes a file that the other branch has modified.

Why Do Conflicts Happen?

Two people (or two branches) edit the same line in a file differently.
One branch deletes a file that the other branch edits.
Changes are made to the same section of a file in both branches.

Git tries to merge changes automatically, but if it’s unsure which change to keep, it stops and asks you to decide.

Deleting Branches

Mon, 01 Jan 0001 00:00:00 +0000

Why Delete Branches?

Branches are great for working on features, bug fixes, or experiments.
But once a branch has served its purpose (for example, a feature is merged into main), it’s a good idea to delete it.
This keeps your repository clean and avoids confusion.

Deleting Local Branches

A local branch exists only on your computer.

Delete a Local Branch (Safe)

git branch -d <branch-name>

Deletes the branch only if it has been fully merged into your current branch.
Prevents you from accidentally deleting work that hasn’t been saved elsewhere.

Example:

Understanding Remote Branches

Mon, 01 Jan 0001 00:00:00 +0000

What is a Remote Branch?

A remote branch is a branch that exists on a remote repository (like GitHub, GitLab, or Bitbucket), not just on your local computer.
Remote branches let you collaborate with others by sharing your work and keeping your local repository in sync with the remote server.

How Do Remote Branches Work?

When you clone a repository, Git creates local copies of all the remote branches.
Remote branches are read-only references to the state of branches on the remote server.
They are named like origin/main, origin/feature/login, etc.
- origin is the default name for the remote you cloned from.

Common Remote Branch Commands

1. Listing Remote Branches

List only remote branches:

Understanding Upstream Branches

Mon, 01 Jan 0001 00:00:00 +0000

What is an Upstream Branch?

An upstream branch in Git is the remote branch that your local branch is “tracking.”
This means your local branch knows which remote branch it should compare itself to when you run commands like git pull or git push—so you don’t have to specify the remote branch every time.

Why Use Upstream Branches?

Convenience:
You can simply run git pull or git push without extra arguments, and Git knows which remote branch to use.
Collaboration:
Keeps your local branch in sync with the team’s shared branch on the remote server.
Safety:
Helps prevent mistakes, like pushing to the wrong branch.

How Do You Set an Upstream Branch?

When Creating a Local Branch from a Remote Branch

If you create a local branch from a remote branch, Git usually sets the upstream automatically:

Renaming Branches

Mon, 01 Jan 0001 00:00:00 +0000

Why Rename a Branch?

Sometimes you create a branch with a quick name, but later want something more descriptive or consistent.
Renaming branches helps keep your repository organized and clear for everyone working on it.

Renaming a Local Branch

Rename the Current Branch

If you are on the branch you want to rename:

git branch -m new-branch-name

-m stands for “move” (rename).
This changes the branch name in your local repository.

Example:

Interactive Rebase in Git

Mon, 01 Jan 0001 00:00:00 +0000

What is Interactive Rebase?

Interactive rebase is a powerful Git feature that lets you rewrite, edit, reorder, squash, or even delete commits in your branch’s history.
It’s called “interactive” because Git opens an editor and lets you choose exactly what happens to each commit.

Why Use Interactive Rebase?

Clean up messy commit history before sharing your work.
Combine (squash) multiple commits into one.
Edit commit messages for clarity or consistency.
Reorder commits to make history logical.
Remove unwanted commits (like mistakes or debug code).
Split a commit into smaller, more focused commits.

How to Start an Interactive Rebase

Decide how many commits you want to work with (counting backwards from your current commit):

Squash Commits with Interactive Rebase

Mon, 01 Jan 0001 00:00:00 +0000

What is Squashing?

Squashing means combining multiple commits into a single commit.
This is useful for cleaning up your commit history before merging a feature branch—so instead of a long list of tiny or “work in progress” commits, you have one clear, meaningful commit.

Why Squash Commits?

Cleaner History:
Makes your project history easier to read and understand.
Atomic Changes:
Groups related changes together, making it easier to review and revert if needed.
Professionalism:
Shows a tidy, intentional history when collaborating or submitting pull requests.

How to Squash Commits Using Interactive Rebase

Suppose your branch has several commits you want to squash into one.

Reordering Commits with Interactive Rebase

Mon, 01 Jan 0001 00:00:00 +0000

Why Reorder Commits?

Sometimes, you make commits in an order that doesn’t make sense for the project’s history.
Maybe you fixed a typo before adding the main feature, or you want related changes grouped together.
Reordering commits helps you organize your history so it’s logical, readable, and easy to review.

How to Reorder Commits in Git

You use interactive rebase to reorder commits.
This lets you pick up any commit and move it before or after others.

Reordering Commits

Mon, 01 Jan 0001 00:00:00 +0000

Why Reorder Commits?

How to Reorder Commits in Git

You use interactive rebase to reorder commits.
This lets you pick up any commit and move it before or after others.

Branching Workflows

Mon, 01 Jan 0001 00:00:00 +0000

What is a Branching Workflow?

A branching workflow is a strategy for how you and your team use branches to organize work in a Git repository.
It defines how features, fixes, releases, and collaboration happen—making teamwork smoother and your project history clearer.

Why Use a Workflow?

Organization:
Keeps features, fixes, and releases separate.
Collaboration:
Allows multiple people to work independently.
Safety:
Protects stable code from unfinished or experimental changes.
Traceability:
Makes it easy to see what was done, when, and by whom.

Common Branching Workflows

1. Feature Branch Workflow

Each new feature or fix gets its own branch.
Branches are created from the main branch (often called main or master).
When finished, the feature branch is merged back into main.

Example:

Branch Protection

Mon, 01 Jan 0001 00:00:00 +0000

What is Branch Protection?

Branch protection is a set of rules that prevent unwanted changes to important branches in your repository—like main, master, or develop.
It’s a safety feature, usually managed on platforms like GitHub, GitLab, or Bitbucket, to keep your codebase stable and secure.

Why Use Branch Protection?

Prevent mistakes:
Stops accidental force-pushes, deletions, or direct commits to critical branches.
Enforce code review:
Require pull requests and approvals before merging changes.
Maintain stability:
Ensure only tested, reviewed code reaches production branches.
Automate checks:
Require passing tests, successful builds, or other checks before merging.

Common Branch Protection Rules

1. Require Pull Requests

Disallow direct pushes to protected branches.
All changes must go through a pull request (PR) for review.

2. Require Reviews and Approvals

Specify that one or more team members must approve a PR before it can be merged.

3. Require Status Checks

Only allow merging if automated tests, builds, or other checks pass.

4. Restrict Who Can Push

Limit who can push, merge, or delete the branch (e.g., only admins or maintainers).

5. Prevent Force-Pushes and Deletion

Block force-pushes (git push --force) to avoid rewriting history.
Prevent accidental or malicious branch deletion.

How to Set Up Branch Protection

On GitHub

Go to your repository on GitHub.
Click Settings > Branches.
Add a branch protection rule for your chosen branch (e.g., main).
Select the rules you want (require PRs, reviews, status checks, etc.).
Save the rule.

On GitLab

Go to your repository.
Click Settings > Repository > Protected Branches.
Choose the branch and set permissions for who can push, merge, or delete.

On Bitbucket

Go to your repository.
Click Repository Settings > Branch permissions.
Add rules for your branches.

Example: GitHub Branch Protection

Require pull request before merging.
Require at least one approval.
Require status checks to pass.
Restrict who can push.
Block force-pushes and deletion.

When to Protect a Branch

Production branches:
Always protect main, master, or any branch deployed to users.
Release branches:
Protect branches used for releases or hotfixes.
Develop/integration branches:
Protect if multiple people merge features into them.

Tips for Branch Protection

Document your rules:
Make sure everyone on your team knows which branches are protected and why.
Review regularly:
Update protection rules as your team or workflow changes.
Combine with workflows:
Use protection rules alongside branching workflows for maximum safety.

Tip:
Set it up early—don’t wait for a mistake to happen!

Bonus Concepts

Mon, 01 Jan 0001 00:00:00 +0000

This section covers advanced and useful Git concepts related to branching, history, and project management.
Even if you’re new to Git, these tools and ideas will help you understand and recover your project in tricky situations!

Tags vs Branches

What is a Tag?

A tag is a fixed pointer to a specific commit.
Used to mark important points in history, like releases (v1.0.0, v2.1.3).
Tags do not move—they always point to the same commit.

Create a tag:

How to Contribute a Blog Post to gitx Documentation

Thu, 02 Oct 2025 00:00:00 +0000

Welcome to the gitx blog! We’re excited to have you here and even more excited if you’re thinking about contributing your own post. This guide will walk you through the entire process of creating and submitting a blog post to our documentation site.

What Should You Write About?

We welcome blog posts on any topic related to Git! Here are some ideas to get you started:

Git Commands Deep Dive: Explain a specific Git command in detail (like git bisect, git rebase, or git cherry-pick)
Git Workflows: Share best practices for team collaboration using Git
Git History & Fun Facts: Interesting trivia about Git’s development or its creator
Personal Stories: How Git helped you solve a problem or improved your workflow
Tips & Tricks: Lesser-known Git features that make developers more productive
Tutorials: Step-by-step guides for achieving specific tasks with Git

Step-by-Step: How to Contribute

1. Fork the Repository

Start by forking the gitxtui/docs repository on GitHub. Click the “Fork” button in the top-right corner of the repository page.

Intro to github actions

Thu, 02 Oct 2025 00:00:00 +0000

The problem

Have you ever thought about how big tech companies manage to push code into production so seamlessly? How do they make sure thousands of test cases run automatically, catch issues before they break things, and still ship updates quickly? It almost feels like magic—code goes in, and polished features come out the other side without chaos.

The Solution

The secret isn’t magic at all—it’s automation. In this blog post, we’ll explore how GitHub Actions, developer workflows, and CI/CD pipelines work together to handle testing, automatic deployments, and smooth releases. By the end, you’ll see how these tools make modern software development faster, safer, and much less stressful.

Git Commands That Will Actually Save Your Day

Thu, 02 Oct 2025 00:00:00 +0000

Look, we all know git commit, git push, and git pull. But Git has a treasure trove of commands that can save you hours of frustration—if only you knew they existed. Here are the genuinely useful ones that deserve way more attention.

`git reflog` — Your Time Machine When Things Go Wrong

Ever executed git reset --hard and immediately regretted it? Or accidentally deleted a branch you needed? This is your safety net.

How I Resolve Merge Conflicts Easily

Thu, 02 Oct 2025 00:00:00 +0000

How I Resolve Merge Conflicts Easily

Merge conflicts happen when Git can’t automatically combine changes from different people. It’s not scary — it just means Git needs you to decide which changes to keep.

Steps I Follow to Resolve Conflicts

Check the conflicted files
Git will tell you which files have conflicts after a merge or pull.
Open the files and look for conflict markers
You’ll see things like <<<<<<< HEAD, =======, and >>>>>>> branch-name.

Mon, 01 Jan 0001 00:00:00 +0000

Search Results

Mon, 01 Jan 0001 00:00:00 +0000

gitx

Basics

Installing gitx

Installation Script

Using go install

Introduction to Git

Overview

What is it?

Project Roadmap

✅ Completed Done

🚀 In Progress Active

📋 Planned Upcoming

Getting started with GIT

1. Installation

2. The Git Workflow (The Big Picture)

Keybinds

Overview

Configuration

Key Specification Format

Custom Themes

Overview

Built-in Themes

Using Built-in Themes

The Three Stages in Git

What Are the Three Stages in Git?

1. Working Directory

Stashing Changes in Git

What is Stashing?

Why Use Stash?

How Does Stash Work?

Working with Branches

Listing Branches

Creating Branches

Creating a Branch

Command 1: Create only

Command 2: Create + switch

Command 3: Modern way

Working with Remotes

Why Not Just Share Files?

Best Practices for Using Git

1. Commit Often, But Meaningfully

2. Write Clear Commit Messages

3. Use Branches for Features and Fixes

4. Pull and Merge Regularly

5. Review Before You Commit

6. Clean Up Branches

7. Use .gitignore

8. Protect Important Branches

9. Test Before You Push

10. Document Your Workflow

Summary Table

Understanding HEAD

What is HEAD in Git?

HEAD: Your Current Position

How HEAD Moves

Detached HEAD State

Merging Branches

What is Merging?

Why Merge?

How Does Merging Work?

Handling Merge Conflicts

What is a Merge Conflict?

Why Do Conflicts Happen?

Deleting Branches

Why Delete Branches?

Deleting Local Branches

Delete a Local Branch (Safe)

Understanding Remote Branches

What is a Remote Branch?

How Do Remote Branches Work?

Common Remote Branch Commands

1. Listing Remote Branches

Understanding Upstream Branches

What is an Upstream Branch?

Why Use Upstream Branches?

How Do You Set an Upstream Branch?

When Creating a Local Branch from a Remote Branch

Renaming Branches

Why Rename a Branch?

Renaming a Local Branch

`git reflog` — Your Time Machine When Things Go Wrong