Ensiklopedia VibeKoding: Principles of Git Version Control.Ensiklopedia VibeKoding: Principles of Git Version Control.
> ๐ก Learning Guide: This chapter is written specifically for people who have never used Git. We won't start by making you memorize commands. Instead, we'll first understand "what problem Git is solving for you," and then step-by-step connect commands and concepts. After reading, you should be able to independently: make local commits, create branches, and push to GitHub.> ๐ก Learning Guide: This chapter is written specifically for people who have never used Git. We won't start by making you memorize commands. Instead, we'll first understand "what problem Git is solving for you," and then step-by-step connect commands and concepts. After reading, you should be able to independently: make local commits, create branches, and push to GitHub.
Git was created to solve these three problems.Git was created to solve these three problems.
Git is a Version Control System. Its essence is: recording every "save" operation you make, forming a complete historical timeline that lets you return to any previous point in history at any time.Git is a Version Control System. Its essence is: recording every "save" operation you make, forming a complete historical timeline that lets you return to any previous point in history at any time.
It's no exaggeration to say that Git is one of the most important tools in modern software development. Nearly every company and every open-source project uses it.It's no exaggeration to say that Git is one of the most important tools in modern software development. Nearly every company and every open-source project uses it.
------
Many beginners confuse these two concepts. Let's clarify:Many beginners confuse these two concepts. Let's clarify:
| Git | GitHub | |
|---|---|---|
| What is it | A version control tool running on your computer | A website that hosts Git repositories (in the cloud) |
| Where is it | Your local computer | On the internet |
| Can it be used independently | โ Yes, it manages local history only | โ Needs to be used with Git |
| Analogy | Your local diary notebook | Cloud storage for your diary |
Simply put: Git is the tool, GitHub is the hosting service. Just like Word is the tool and OneDrive is cloud storage โ they work together but are not the same thing.Simply put: Git is the tool, GitHub is the hosting service. Just like Word is the tool and OneDrive is cloud storage โ they work together but are not the same thing.
Besides GitHub, similar services include GitLab, Gitee (China-based), and others.Besides GitHub, similar services include GitLab, Gitee (China-based), and others.
------
This is the most important design in all of Git. Once you understand these three areas, you understand the soul of Git.This is the most important design in all of Git. Once you understand these three areas, you understand the soul of Git.
Git divides your file states into three layers:Git divides your file states into three layers:
Working DirectoryWorking Directory
This is your regular folder โ all the files you can see and are currently editing are here. You can change anything freely; Git will sense what you've changed but won't record anything.This is your regular folder โ all the files you can see and are currently editing are here. You can change anything freely; Git will sense what you've changed but won't record anything.
Staging Area (Index)Staging Area (Index)
This is a "pre-commit transit station." You can "put" files from the working directory that you want to save into the staging area โ like putting packages into a shipping box. They haven't been sent out yet, but you've chosen what to send.This is a "pre-commit transit station." You can "put" files from the working directory that you want to save into the staging area โ like putting packages into a shipping box. They haven't been sent out yet, but you've chosen what to send.
RepositoryRepository
This is the permanent archive of historical records, hidden inside the .git folder. Every time you run git commit, the contents of the staging area are sealed into the repository, forming an immutable historical record.This is the permanent archive of historical records, hidden inside the .git folder. Every time you run git commit, the contents of the staging area are sealed into the repository, forming an immutable historical record.
๐ Try it out: Click the command buttons in order and observe how files flow between the three areas.๐ Try it out: Click the command buttons in order and observe how files flow between the three areas.
Many beginners ask: why can't you just save with one click? Why add first, then commit?Many beginners ask: why can't you just save with one click? Why add first, then commit?
Because in real-world development, you often don't want to commit all changes together.Because in real-world development, you often don't want to commit all changes together.
For example: today you modified 5 files:For example: today you modified 5 files:
login.js: completed the login feature (want to commit)login.js: completed the login feature (want to commit)style.css: adjusted the login page styles (want to commit)style.css: adjusted the login page styles (want to commit)debug.log: temporary debug output (don't want to commit)debug.log: temporary debug output (don't want to commit)experiment.js: testing a new feature, not finished yet (don't want to commit)experiment.js: testing a new feature, not finished yet (don't want to commit)todo.txt: your personal notes (don't want to commit)todo.txt: your personal notes (don't want to commit)Without a staging area, you'd either commit all 5 files (messy commit history) or commit none of them.Without a staging area, you'd either commit all 5 files (messy commit history) or commit none of them.
With a staging area, you can precisely control: git add login.js style.css โ only put these two files into the shipping box, then commit. This commit clearly records "login feature completed."With a staging area, you can precisely control: git add login.js style.css โ only put these two files into the shipping box, then commit. This commit clearly records "login feature completed."
------
After installing Git (macOS comes with it; for Windows, download from git-scm.com), open the terminal and navigate to your project folder:After installing Git (macOS comes with it; for Windows, download from git-scm.com), open the terminal and navigate to your project folder:
bash # Initialize a Git repository in the current folder git init # Git will create a hidden .git folder where all history is stored # Output: Initialized empty Git repository in .../your-project/.git/
The first time you use it, you also need to tell Git who you are (this information will be attached to every commit):The first time you use it, you also need to tell Git who you are (this information will be attached to every commit):
bash git config --global user.name "Your Name" git config --global user.email "your@email.com"
After initialization, 90% of daily development is just repeating these three steps:After initialization, 90% of daily development is just repeating these three steps:
Step 1: Check StatusStep 1: Check Status
bash git status
This is the command you'll use the most, bar none. It tells you:This is the command you'll use the most, bar none. It tells you:
Step 2: Put Files into the Staging AreaStep 2: Put Files into the Staging Area
bash # Add a single file git add login.js # Add multiple files git add login.js style.css # Add all modified files in the current folder (. means "everything") git add .
> โ ๏ธ Common beginner pitfall: git add . is very convenient but adds all changes, including files you may not want to commit. Build the habit of precise adds, or use .gitignore to exclude files you don't want to track (covered later).> โ ๏ธ Common beginner pitfall: git add . is very convenient but adds all changes, including files you may not want to commit. Build the habit of precise adds, or use .gitignore to exclude files you don't want to track (covered later).
Step 3: Commit with a MessageStep 3: Commit with a Message
bash git commit -m "feat: add user login feature"
The text in quotes after -m is called the commit message. This is written for your future self and your teammates โ make it meaningful.The text in quotes after -m is called the commit message. This is written for your future self and your teammates โ make it meaningful.
bash # โ Bad examples โ reading them tells you nothing about what was done git commit -m "update" git commit -m "fix" git commit -m "changed some things" # โ Good examples: type + colon + one-sentence description git commit -m "feat: add user login feature" git commit -m "fix: fix white screen issue on iOS Safari homepage" git commit -m "docs: update deployment instructions in README" git commit -m "refactor: split UserService into independent module" git commit -m "style: unify code indentation to 2 spaces"
Common prefix meanings:Common prefix meanings:
| Prefix | Meaning |
|---|---|
feat: | New feature |
fix: | Bug fix |
docs: | Documentation changes |
style: | Code formatting (no functional change) |
refactor: | Code refactoring (same functionality, improved structure) |
chore: | Build, tools, dependencies |
test: | Testing related |
Build this habit, and months later when you browse the history, you'll know at a glance what each commit did. This is especially important in team collaboration.Build this habit, and months later when you browse the history, you'll know at a glance what each commit did. This is especially important in team collaboration.
bash # Detailed format (full info for each commit) git log # Compact format (one line per commit, recommended for daily use) git log --oneline # Example output: # a1b2c3d (HEAD -> main) feat: add user login feature # 9f3e1b2 init: project initialization
------
Branches are Git's most powerful โ and also most confusing for beginners โ feature. But once you understand them, you'll find the design very elegant.Branches are Git's most powerful โ and also most confusing for beginners โ feature. But once you understand them, you'll find the design very elegant.
Imagine you're playing an RPG game with a critical choice:Imagine you're playing an RPG game with a critical choice:
If you make Choice A directly on your main save file and fail, your entire game progress is ruined.If you make Choice A directly on your main save file and fail, your entire game progress is ruined.
But if you copy your save file and challenge the boss in the copy:But if you copy your save file and challenge the boss in the copy:
Git branches are this "copy save" mechanism.Git branches are this "copy save" mechanism.
In Git, the main (or master) branch is your "main save," which should always remain stable and usable. When you want to develop a new feature, you create a new branch from main, develop and test there, and merge back to main when done.In Git, the main (or master) branch is your "main save," which should always remain stable and usable. When you want to develop a new feature, you create a new branch from main, develop and test there, and merge back to main when done.
๐ Try it out: Click the command buttons in order and observe how the branch graph below forks, extends, and eventually merges. Pay close attention to the HEAD label's position โ it always points to "where you currently are."๐ Try it out: Click the command buttons in order and observe how the branch graph below forks, extends, and eventually merges. Pay close attention to the HEAD label's position โ it always points to "where you currently are."
Create and switch to a new branch:Create and switch to a new branch:
bash # Method 1: Create first, then switch (two steps) git branch feature-login # Create branch git checkout feature-login # Switch to it # Method 2: One step (recommended) git checkout -b feature-login # Output: Switched to a new branch 'feature-login'
After creating a branch, your command prompt will show the current branch name, for example:After creating a branch, your command prompt will show the current branch name, for example:
CODE user@mac ~/project (feature-login) $
View all branches:View all branches:
bash git branch # Output (* indicates the current branch): # * feature-login # main
Develop normally on a branch:Develop normally on a branch:
bash # On the feature-login branch, modify code, add, commit โ exactly the same as usual git add login.js git commit -m "feat: add login form HTML structure" git add login.js api.js git commit -m "feat: complete login API integration"
These commits exist only on the feature-login branch. The main branch has no idea what you've done.These commits exist only on the feature-login branch. The main branch has no idea what you've done.
Switch back to the main branch and merge:Switch back to the main branch and merge:
bash # Switch back to main git checkout main # Merge all changes from feature-login git merge feature-login # After merging, you can delete the branch (optional) git branch -d feature-login
| Scenario | Recommendation | Reason |
|---|---|---|
| Developing a new feature | โ Create a branch | Doesn't affect main line until feature is done; can abandon at any time |
| Fixing an urgent production bug | โ
Create a hotfix-xxx branch from main | Fix and merge directly to production, without bringing in unfinished features |
| Parallel development with teammates | โ Each person creates their own branch | No interference; merge via Pull Request when done |
| Fixing a single typo | โ Just fix it on main | Very low risk, no need for a separate branch |
In real projects, teams usually agree on branch naming conventions and purposes:In real projects, teams usually agree on branch naming conventions and purposes:
| Branch Name | Purpose | Characteristics |
|---|---|---|
main / master | Stable production code | Only tested code can enter; no direct pushes |
dev / develop | Daily integration branch | All feature branches merge here first; after testing, goes to main |
feature/xxx | Specific feature development | e.g., feature/user-login; merges to dev when complete |
hotfix/xxx | Urgent fixes | Created from main; after fixing, merges directly back to main and dev |
------
Everything you've learned so far is about local Git operations โ all history is stored on your own computer. To share code with teammates, you need a remote repository, such as GitHub or GitLab.Everything you've learned so far is about local Git operations โ all history is stored on your own computer. To share code with teammates, you need a remote repository, such as GitHub or GitLab.
Think of a remote repository as the team's "shared save file":Think of a remote repository as the team's "shared save file":
push (upload) to the remote repositoryWhen done, push (upload) to the remote repositorypull (download) the latest content from the remote to their local machineTeammates pull (download) the latest content from the remote to their local machine๐ Try it out: Click the commands in order to experience the complete flow from linking a remote repository, pushing, to pulling teammates' updates.๐ Try it out: Click the commands in order to experience the complete flow from linking a remote repository, pushing, to pulling teammates' updates.
Step 1: Create a new repository on GitHub (click the + in the upper right corner โ New repository). Don't check any initialization options.Step 1: Create a new repository on GitHub (click the + in the upper right corner โ New repository). Don't check any initialization options.
Step 2: Back in your local terminal, link the remote repository:Step 2: Back in your local terminal, link the remote repository:
bash # Link the local repository with the GitHub repository # "origin" is the remote repository's alias โ a conventional name (you can change it, but there's no need) git remote add origin https://github.com/your-username/your-repo.git # Confirm the link was successful git remote -v # Output: # origin https://github.com/your-username/your-repo.git (fetch) # origin https://github.com/your-username/your-repo.git (push)
Step 3: Push local content to remote:Step 3: Push local content to remote:
bash # First push. -u means "for future git push, default to origin's main branch" git push -u origin main # After that, each push only needs: git push
Push (you made changes and want teammates to see them):Push (you made changes and want teammates to see them):
bash git push
Pull (teammates made changes and you need to sync):Pull (teammates made changes and you need to sync):
bash git pull
git pull is actually a combination of two commands:git pull is actually a combination of two commands:
git fetch: Download the latest commits from the remote repositorygit fetch: Download the latest commits from the remote repositorygit merge: Merge the downloaded content into your current branchgit merge: Merge the downloaded content into your current branchGetting someone else's project from GitHub for the first time:Getting someone else's project from GitHub for the first time:
bash # Copy the entire remote repository to your local machine (only needs to be done once) git clone https://github.com/someone/some-project.git # clone automatically sets up the remote link, so you can just push/pull afterwards
CODE Your Computer (Local Repo) โโ GitHub (Remote Repo) git push: Local โ Remote (you made changes, upload for teammates) git pull: Remote โ Local (teammates made changes, download to your machine) git clone: Remote โ Local (first-time full copy of the entire repository)
> Best practice: git pull at the start of each workday to get the latest code; git push when finishing work or completing a feature to back up promptly and let teammates see your progress.> Best practice: git pull at the start of each workday to get the latest code; git push when finishing work or completing a feature to back up promptly and let teammates see your progress.
------
Conflicts are inevitable in collaboration, but they're not that scary.Conflicts are inevitable in collaboration, but they're not that scary.
When you and a teammate both modify the same line in the same file, Git doesn't know whose version to use during a merge, so a conflict occurs.When you and a teammate both modify the same line in the same file, Git doesn't know whose version to use during a merge, so a conflict occurs.
For example:For example:
login.js: const timeout = 3000You wrote on line 5 of login.js: const timeout = 3000const timeout = 5000Your teammate simultaneously wrote on the same line: const timeout = 5000git pull or git merge, Git discovers this contradiction and "pauses" to tell you: I don't know which one to use โ you decide.When you git pull or git merge, Git discovers this contradiction and "pauses" to tell you: I don't know which one to use โ you decide.Git inserts special markers at the conflict location:Git inserts special markers at the conflict location:
javascript function login() { const url = '/api/login' <<<<<<< HEAD const timeout = 3000 // Your version ======= const timeout = 5000 // Teammate's version >>>>>>> feature/update-timeout return fetch(url, { timeout }) }
<<<<<<< HEAD and =======: your current branch's contentBetween <<<<<<< HEAD and =======: your current branch's content======= and >>>>>>> xxx: the content being merged inBetween ======= and >>>>>>> xxx: the content being merged inStep 1: Open the conflicted file and find all <<<<<<< markers (editors like VS Code will usually highlight them automatically)Step 1: Open the conflicted file and find all <<<<<<< markers (editors like VS Code will usually highlight them automatically)
Step 2: Decide which code to keep, then manually edit the file, removing all marker symbols (<<<<<<<, =======, >>>>>>>).Step 2: Decide which code to keep, then manually edit the file, removing all marker symbols (<<<<<<<, =======, >>>>>>>).
For example, deciding to use 5000 (teammate's version):For example, deciding to use 5000 (teammate's version):
javascript function login() { const url = '/api/login' const timeout = 5000 // Adopt teammate's change return fetch(url, { timeout }) }
Step 3: Commit againStep 3: Commit again
bash # Mark the conflict as resolved git add login.js # Complete the merge commit (Git will auto-generate a merge commit message) git commit
config.js), give your teammates a heads-upCommunicate: Before modifying shared files (like config.js), give your teammates a heads-up------
------
This is the standard workflow when you join a new team or project โ you can follow it directly:This is the standard workflow when you join a new team or project โ you can follow it directly:
bash # โ Day one: clone the project to your local machine (only once) git clone https://github.com/team/project.git cd project # โก Start of each workday: pull the latest code to ensure yours is up to date git pull origin main # โข Create your own feature branch (don't modify main directly) git checkout -b feature/user-profile # โฃ Normal development... write code... # โค After completing a small feature, commit immediately (don't hoard changes) git add src/UserProfile.vue git commit -m "feat: complete user avatar upload feature" git add src/UserProfile.vue src/api/user.js git commit -m "feat: complete user profile editing API" # โฅ Push your branch to remote so teammates can see it git push origin feature/user-profile # โฆ Create a Pull Request (PR) on GitHub, requesting merge into main # (This step is done on the GitHub website) # โง Wait for teammates' Code Review, make changes based on feedback, continue committing + pushing # โจ After PR is merged, go back to main, update local, delete the feature branch git checkout main git pull git branch -d feature/user-profile
------
Some files you don't want to commit to the Git repository, for example:Some files you don't want to commit to the Git repository, for example:
node_modules/: dependency packages, huge in size, can be regenerated with npm installnode_modules/: dependency packages, huge in size, can be regenerated with npm install.env: environment variable file that may contain database passwords, API keys โ absolutely must not be uploaded to public repositories.env: environment variable file that may contain database passwords, API keys โ absolutely must not be uploaded to public repositories*.log: log files*.log: log files.DS_Store: macOS auto-generated hidden files.DS_Store: macOS auto-generated hidden filesdist/, build/: build artifacts that can be rebuiltdist/, build/: build artifacts that can be rebuiltCreate a .gitignore file in the project root directory with rules for files you don't want to track:Create a .gitignore file in the project root directory with rules for files you don't want to track:
gitignore # Dependencies node_modules/ # Environment variables (important! passwords must not be committed) .env .env.local # Build output dist/ build/ # System files .DS_Store Thumbs.db # Logs *.log
GitHub has .gitignore templates for various languages and frameworks: [github.com/github/gitignore](https://github.com/github/gitignore)GitHub has .gitignore templates for various languages and frameworks: [github.com/github/gitignore](https://github.com/github/gitignore)
------
| Term | English | Explanation |
|---|---|---|
| Repository | Repository (Repo) | The database storing all version history of a project, inside the .git folder |
| Commit | Commit | A complete version record, like a game save point, with a description and timestamp |
| Branch | Branch | An independent line of development, like parallel timelines that don't affect each other |
| Merge | Merge | Integrating changes from one branch into another |
| Conflict | Conflict | When the same line of code is modified by multiple people and Git doesn't know which version to use, requiring manual resolution |
| Stage | Stage / Index | The action of putting modifications into the "ready to commit" list |
| Remote | Remote | A cloud copy of the repository (GitHub / GitLab / Gitee) |
| Clone | Clone | Copying an entire remote repository to your local machine |
| Push | Push | Uploading local commits to a remote repository |
| Pull | Pull | Downloading the latest content from remote and merging it locally |
| HEAD | HEAD | A pointer to the current branch/commit, indicating "where you are now" |
| origin | origin | The default alias for a remote repository (a conventional name) |
| stash | Stash | Temporarily saving uncommitted changes, useful when switching tasks |
| PR / MR | Pull Request / Merge Request | A request to merge your branch into the main branch, usually requiring teammate review |