DOCSEARCHbyAlgolia
Submit Docs

Git Guide and Reference

website·Indexed 31 days ago

https://rumosky.net

A comprehensive guide to Git covering installation, basic operations (commit, add, checkout), branch management strategies, rebase, tag operations, and remote repository configuration. Includes a command quick reference and solutions for common issues such as merge conflicts, unrelated histories, and line ending warnings.

Tokens
9.1K
Snippets
79
Records
92
Agent score
50%

What's inside Git

  1. Understand the Git Working Directory and Repository structure

    In Git, the Working Directory is the actual directory on your computer where your project files reside. The Repository is a hidden .git directory located within the working directory; it contains the version control data and the 'stage' (also known as the 'index'), which is the staging area for changes before they are committed.

  2. Understand how Git tracks text vs binary files

    Git tracks changes (deltas) rather than entire files. For text files (e.g., .txt, HTML, source code), Git can track specific line-by-line modifications. For binary files (e.g., images, videos), Git cannot track internal changes; it only records that the file was modified and tracks the version as a whole (e.g., noting a size change from 100KB to 120KB) without knowing what specifically changed inside the file.

  3. Understand the purpose and behavior of Git tags

    Git tags are used to mark specific points in a repository's history as important, typically for releasing a version (e.g., v1.2). While a tag acts as a snapshot of the repository at a specific moment, it is technically a pointer to a specific commit. Unlike branches, tags are immutable; once created, they cannot be moved to a different commit. This provides a human-readable alias for a commit hash, making it easier to identify and retrieve specific releases.

  4. Use Git branches for isolated feature development

    Git branches allow developers to work on new features in isolation without affecting the main codebase or blocking other team members. Because Git branches are lightweight, creating, switching, and deleting them typically takes less than one second, regardless of the number of files in the repository.

  5. Apply a specific commit to the current branch using git cherry-pick

    When a bug fix has been committed to one branch (e.g., master) and you want to apply the exact same changes to another branch (e.g., dev) without merging the entire branch, use git cherry-pick. This 'copies' the specific commit to your current branch to avoid duplicating manual work.
    git cherry-pick <commit_id>

  6. Switch branches using git switch

    The git switch command was introduced in Git version 2.23 to provide a more intuitive way to switch branches, separating this functionality from git checkout (which is also used for undoing file changes). If you encounter the error git: 'switch' is not a git command, you must upgrade your Git installation to version 2.23 or later.
    # Check current Git version
git --version

# Upgrade Git (for versions before 2.17.1)
git update

# Upgrade Git (for versions 2.17.1 and later on Windows)
git update-git-for-windows

  7. Merge updates from an upstream repository into a modified fork

    When you have a fork (Repository B) based on an open-source project (Repository A), and you want to incorporate new features from A without overwriting your custom modifications in B, follow this workflow. This process uses a temporary merge branch to isolate conflict resolution before updating the main branch of the fork.
    # 1. Add the original repository A as a remote named 'upstream'
cd path/to/B
git remote add upstream path/to/A

# 2. Fetch the latest code from the upstream repository
git fetch upstream

# 3. Create a new temporary branch for the merge operation
git checkout -b merge-upstream

# 4. Merge the upstream main branch into the temporary branch
# If the upstream branch is not 'main', replace it with the correct branch name
git merge upstream/main

# NOTE: If you see 'fatal: refusing to merge unrelated histories', use:
git merge upstream/main --allow-unrelated-histories

# 5. Resolve any merge conflicts manually, then stage and commit
git add .
git commit

# 6. Switch back to the main branch of Repository B and merge the temporary branch
git checkout main
git merge merge-upstream

# 7. Resolve any remaining conflicts and push the final result to Repository B
git push origin main

  8. Clone a remote Git repository to a local machine

    To copy a remote repository to your local environment, use the git clone command followed by the repository URL. The URL can be either an SSH or HTTP link, though using a native SSH link is recommended for better speed and security. This is the standard workflow when the remote repository already exists and you need to start working on it locally.
    git clone <url>
# Example: git clone git@github.com:user/repo.git

  9. Configure SSH connection for GitHub or Gitee

    To securely connect a local Git repository to a remote host like GitHub or Gitee, use the SSH protocol. This requires generating a public/private key pair on your local machine and adding the public key to your remote account settings.
    # 1. Generate the SSH key pair
ssh-keygen -t rsa -C "youremail@example.com"

# Note: Press Enter three times to skip passphrase/password prompts.

  10. Initialize a local Git repository

    To start tracking a project with Git, create an empty directory and run git init. This creates a .git hidden directory containing the repository's configuration files, which should not be modified manually.
    git init

  11. Implement a basic Git branching strategy for team development

    For effective team collaboration, follow these branching principles:

    1. master branch: Keep this branch highly stable. Use it exclusively for releasing new versions; do not perform daily development work here.
    2. dev branch: Use this as the primary integration branch where development occurs. It is considered unstable. When a version (e.g., 1.0) is ready for release, merge the dev branch into the master branch.
    3. Feature branches: Each developer should work on their own individual branch and periodically merge their changes into the dev branch.

  12. Best practices for Git branching and collaboration

    To maintain a clean project history and avoid complex merge conflicts (cross-merges), follow these guidelines:

    1. Commit frequently, push sparingly: In collaborative environments, frequent pushes increase the likelihood of merge conflicts. Use local commits to track progress and push only when stable.
    2. Adopt Git Flow: Use a multi-branch structure to organize development.
    3. Keep the main branch clean: Perform work and commits on feature branches. Before merging into the main branch, update your local main branch using git pull --rebase to ensure a linear history and avoid multiple common ancestor nodes.
    4. Disable fast-forward merges: Use the --no-ff flag during merges to ensure a merge commit is always created, which preserves the historical existence of the feature branch and keeps the commit graph clear.
    # Update main branch without creating unnecessary merge commits
git pull --rebase

# Merge a branch while disabling fast-forward mode
git merge --no-ff <branch-name>