main

Author: sharpchen

docs/document/Skill/Git/docs/1.Overview.md

@@ -1,10 +1,25 @@
 # Overview
 
-- **Changes & Status**:
+## Concepts
+
+1. **Changes & Status**:
     - a file can be *tracked* or *untracked* which indicates whether the file is recognized by git as part of the repository.
     - a change includes *added*, *deleted*, *modified* at the minimum unit of lines.
     - staging meaning that you're selectively picking untracked files or changes into bucket, and waiting for **committing** them.
-- **Commit**: With staged changes, you're ready to generate a new snapshot, which is called *commit*.
+2. **Commit**: With staged changes, you're ready to generate a new snapshot, which is called *commit*.
     - commits constructs a acyclic graph representing all revisions of your repository.
-    - you can rollback to one snapshot by *Reset*.
-    - a branch is derived from a commit.
+    - you can rollback to one snapshot by `reset`.
+3. **Branching**: a special form of commit that can represent a divergence of the commit graph.
+    - each branch is essentially a **dynamic head commit** of that divergence, it can traverse back to its start point to delineated the branch.
+    - a branch can merge to another on `pull` or `merge`
+4. **Synchronization**: working with remotes and locals
+
+## Getting Help
+
+`git help <subcommand>` is the builtin command to show man page of the specified subcommand on UNIX or opening documentation html page on Windows
+
+For example, open documentation for `git clone` subcommand:
+
+```sh
+git help clone
+```

docs/document/Skill/Git/docs/2.Commit.md

@@ -18,7 +18,7 @@ Git is able to compare base on two commits(usually the current and last commit),
 
 ## Commit Identifier
 
-Each commit is identified by the uniquely generated SHA hash, you can reference the commit using the full hash or the leading 7 digit hash on git commands.
+Each commit is identified by the uniquely generated SHA hash, you can reference the commit using the full hash or the leading 7 digit hash for short.
 Each snapshot instance of that particular commit could be found on `.git/objects/<first-2digits-of-hash>/<restof-hash>`
 
 > [!NOTE]
@@ -28,6 +28,7 @@ Each snapshot instance of that particular commit could be found on `.git/objects
 2. **branch name**: points to **latest** commit of the branch.
 3. **tag name**: points to the commit of that tag.
 4. `HEAD` or `@`: points to the **current** commit you're at.
+    - special identifiers like `HEAD` is independent from any branch, its a primitive and dynamic pointer for your current worktree.
     - for some other special identifier names, see documentation.
 5. `-` or `@{-1}`: previous commit you're at.
     - `-` is not a valid identifier in some scenarios, but you can use it in like `git checkout -` or `git merge -`.
@@ -41,7 +42,7 @@ Three special symbols for traversing back in git:
 1. `@`: reference backward through ***reflog***, you can see such symbol like `HEAD@{1}` in `git reflog` output.
     - `@{-<n>}`: go to nth previously checked out commit by `git checkout`
     - `<commit_identifier>@{<n>}`: go to previous nth commit
-        - `@{<n>}` is equivalent to `<current_branch>@{<n>}`, this is only valid when you're on a branch.
+        - `@{<n>}` is equivalent to `<current_branch>@{<n>}`, this is only valid when you're on a branch(not detached).
 2. `~`: trace back to previous commits through **the first parent** only.
     - `<identifier>~3`: points to previous 3 commit from current branch.
 3. `^`: trace back to previous commits through a specified parent by its index.
@@ -54,14 +55,21 @@ Three special symbols for traversing back in git:
 > [!NOTE]
 > See `git help revisions` for more details
 
-> [!TIP]
-> You can expand the commit hash by special identifier using `git rev-parse <identifier>`
->```console
->$ git rev-parse @~1
->42804017200559f28d12757e729f95dbd18f4998
->$ git rev-parse main
->e7bbe687097f56d152c2291190b67d91eed4cd57
->```
+> [!NOTE]
+> When saying `HEAD` we're referring to the head of worktree which might walk across different branches as you checkout.
+> When a branch name is explicitly specified or elided(representing the current branch), the **reflog** can differ from `HEAD` since it only contains things about the branch.
+> That is, such commit expression with `@` can point to different commit as you specify/elide the identifier or not.
+
+### Identifier Expansion
+
+You can expand the any identifier to full commit hash using `git rev-parse <identifier>`
+
+```console
+$ git rev-parse @~1
+42804017200559f28d12757e729f95dbd18f4998
+$ git rev-parse main
+e7bbe687097f56d152c2291190b67d91eed4cd57
+```
 
 ## Commit Inspection
 

docs/document/Skill/Git/docs/3.Branching.md

@@ -0,0 +1,70 @@
+# Branching
+
+Each branch was deviated from certain commit of another branch, and could have its own `HEAD` when actual divergence was applied.
+So a branch besides the main branch is essentially a sequence of commits starting with a divergence from another branch.
+
+> [!IMPORTANT]
+> Branch is a concept upon commits, the branch is sometimes equivalent to the latest commit of that branch.
+> A branch is just a special commit points to latest commit of that branch and can trace back to the divergence.
+
+## Branch Identifier
+
+1. **branch name**: generally refers to local branch
+2. `<remote>/<branch>`: refers to remote branch **copy fetched** in local
+3. `@{upstream}` or `@{u}`: see [Synchronization](./5.Synchronization.md#remote-branch-identifier)
+
+> [!NOTE]
+> Given the context that *upstream* is of a branch, `git rev-parse @{u}` should return the fetched latest commit hash of remote **in local**.
+
+## Branch Inspection
+
+A branch has its dedicated text file containing its latest commit hash at `./.git/refs/heads/<branch>`
+
+```console
+$ cat ./.git/refs/heads/msbuid_ls
+4bfbc0c67e39f5615e0cdc4535611af1e71040d8
+```
+
+If the latest commit hash is the only thing the branch knows, how could it collect all of the commits when git requires to?
+The fact is, commits are chained with their parent and child, so git can track back along to the point where the branch was diverged.
+
+## Branch Manipulation
+
+> [!NOTE]
+> See `git help branch` and `tldr git-branch`.
+> Or `git help switch` and `tldr git-switch`.
+
+- `git branch`
+    - `-d|--delete`: delete branch
+    - `-m|--move`: rename branch
+    - `-c|--copy`: copy branch
+
+## Merging & Rebasing
+
+1. **General merge**: merges one branch history to another
+    - this generates a **merge commit**, containing the information about all parents that were merged together, the merge commit is added to the branch merged into.
+2. **Fast forward merging**: when there' no actual divergence on graph between the parent branch and child branch, git can simply move the head pointer of current branch directly from the **merge-base** to the top commit of the branch to be merged from 
+    - generates no merge commit by default, but if do want to keep the history, use `git merge --no-ff` even when the history could be linear.
+3. **Rebasing**: move the **divergence point(aka the base)** to another commit.
+    - generates no *merge commit*
+    - alters your local commit history since its entire root of divergence has been changed.
+    - **DO NOT** use `rebase` in public branch, use it only on your local branch.
+        - If you're sure there's only you to work with the public branch(and its sub branches), feel free to `git push --force` to override the history on remote.
+
+> [!IMPORTANT]
+> Always *merge* on public branches, *rebase* on local branches.
+
+### Merge
+
+A merging involves two branches, the subject of the operation is the branch to merge to.
+
+1. checkout to the branch to merge to.
+2. `git merge <another_branch>`
+    - use `--no-ff` to always generate a merge commit.
+
+### Rebasing
+
+Differ from `merge` subcommand, `rebase` is the change on the branch itself, only one branch is involved in the whole operation.
+
+1. checkout to the branch you need to alter its merge-base
+2. `git rebase <commit_identifier>`

docs/document/Skill/Git/docs/4.Branching.md

@@ -1,8 +1,13 @@
 # Git History & Reset
 
-- `git log`: commit logs that can be synchronized with remotes.
+- `git log`: commit logs that generated by traversing commit graph for each time you inspect it.
 - `git reflog`: local operation logs which is more detailed but limited to local repository.
     - **dynamic pointers** such as `HEAD` and branches have their dedicated reflog on their own.
+    - stores at `.git/logs/**`
+
+> [!NOTE]
+> `git reflog` is generally faster to print than `git log` on a **large repository**, because reflog is a literal text file stored at `.git/logs/`
+> While `git log` has to traverse the large graph dynamically which would take a longer time to execute.
 
 ## Commit History Query
 

…/Skill/Git/docs/3.Git History & Reset.md …/Skill/Git/docs/4.Git History & Reset.mddocs/document/Skill/Git/docs/3.Git History & Reset.md renamed to docs/document/Skill/Git/docs/4.Git History & Reset.md docs/document/Skill/Git/docs/3.Git History & Reset.md renamed to docs/document/Skill/Git/docs/4.Git History & Reset.md

@@ -0,0 +1,55 @@
+# Synchronization
+
+- `remote`: a git repository can have one or more remotes targeting to a uri(which means you can even add another local repository as remote with its path) exists in a git host.
+    - `git remote add <remote_name> <uri>`.
+    - each branch also has a *upstream* to track with remote just like the repository.
+- `git fetch [<remote_name>]`: fetch **all** remote commits to local but do nothing, it only fetches and store it at `refs/remotes/<remote_name>/*`
+    - use `git merge <remote_name>/<branch_name>` if you're ready to merge remote commits to local.
+- `pull`: fetch remote commits for current branch and merge them into current branch.
+    - this requires the branch has a *upstream* set.
+
+## Remote
+
+Remotes are implicit commits from the remote repository that can live optionally in your local repository.
+Each remote has its branches, which means each of its branch has a head commit stored in your local repository.
+
+## Remote Inspection
+
+```console
+$ git remote -v # inspect all remotes
+origin  [email protected]:sharpchen/nixpkgs (fetch)
+origin  [email protected]:sharpchen/nixpkgs (push)
+upstream        [email protected]:NixOS/nixpkgs (fetch)
+upstream        [email protected]:NixOS/nixpkgs (push)
+
+$ git branch -v -r # inspect all remote branches
+```
+
+### Remote Naming Convention
+
+The following convention is widely adapted by most git hosts such as github and gitlab, git host would add such remotes by convention when you fork one repository from another.
+
+- `origin`: the remote represents the direct copy in a git host is usually named as *origin*
+    - one repository can have one or more mirrors hosted on different git hosts, the most official one should be *origin*
+    - `git clone` would implicitly name remote to *origin*
+- `upstream`: if current repository is a fork of another, the one been forked should be named as `upstream`.
+
+## Remote Identifier
+
+- **full uri**: such as `[email protected]:NixOS/nixpkgs`
+- **remote name**: such as `origin`
+
+## Remote Branch Identifier
+
+- `<remote_name>/<branch_name>`
+- `<branch_name>@{upstream}` or `<branch_name>@{u}`: attached remote branch of `<branch_name>` **on local**.
+    - `@{upstream}` or `@{u}`: attached remote branch of **current branch**(if you're on a branch)
+
+## Pull
+
+`git pull <remote_name> <branch_name>`
+
+```sh
+git branch -u <remote_name>/<branch_name> [<local_branch>] # make sure you have one upstream attached to the branch
+git pull # pull remote commit from the attached upstream to current branch
+```