main

Author: sharpchen

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

@@ -0,0 +1,10 @@
+# Overview
+
+- **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*.
+    - 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.

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

@@ -0,0 +1,123 @@
+# Commit
+
+Commits are snapshots for each phase of the repository, which allowing you to rollback to any instance of that commit.
+Git is able to compare base on two commits(usually the current and last commit), which is the diff.
+
+- Each commit stores a snapshot of current repository with a unique hash to be identified.
+- A commit can have **one or more** parent from which it was derived.
+- Each snapshot file or folder has a unique hash, and can inspect their content in some way.
+    - the folder snapshot is called `tree`
+    - the file snapshot is `blob`
+    - a commit always shows the snapshot of root of the repository as entry of a commit
+
+> [!NOTE]
+> *Revision* is another synonym of *Commit* in git.
+
+> [!IMPORTANT]
+> **Commit** is the atomic identifier of how git manage the versions, it's the *true* and *real* concept while *branch* and *merge* are just *fake* concepts upon it.
+
+## 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 snapshot instance of that particular commit could be found on `.git/objects/<first-2digits-of-hash>/<restof-hash>`
+
+> [!NOTE]
+> Those *identifier* of commits are called *refs* in git, you could find their representations in `.git/refs`
+
+1. **commit hash**: the most explicit identification of a commit.
+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.
+    - 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 -`.
+6. **commit expression**: see next section.
+
+### Commit Expression
+
+Commit expression is special syntax to reference commits backward from a given point.
+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.
+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.
+    - `<identifier>^2`: points to previous commit through **second** parent of `<identifier>`.
+    - `<identifier>^101`: if you're wild enough to merge from 100 branches, you might need to point to previous commit through the 101-th parent.
+
+> [!TIP]
+> `~1` and `^1` are always equivalent since they would pick the same first parent of the commit.
+
+> [!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
+>```
+
+## Commit Inspection
+
+Commit inspection generally requires `git cat-file -p <hash>`, see `git help cat-file`.
+
+A commit can contain elements:
+- `tree`: the structure of current snapshot, including files and folders.
+- `parent`: the parent commit it was derived from, a commit can have multiple parents.
+- `author`: who did the changes.
+- `committer`: who made the commit, may differ from `author` when rebasing.
+- and more...
+
+```console
+$ git cat-file -p 5eb5a747cfd9b17603b79d7ab64fc4ecee1751e3
+
+tree e060913d1a04d39082981dc116c5a5cd35ba8e52
+parent 02348ec70c2c901e9ecc4be5860330e6dcf911ff
+author sharpchen <[email protected]> 1749697268 +0800
+committer sharpchen <[email protected]> 1749697268 +0800
+```
+
+> [!TIP]
+> It's more general to use `git show <commit_identifier>` to inspect a commit.
+
+### Tree & Blob Inspection
+
+Tree in the inspected commit is a **recursive** structure and also has a hash that can be inspected by `git cat-file -p <hash>`.
+A `blob` represents a real file, a `tree` represents a folder as a container.
+So the tree printed from the commit is actually **the root folder of your repository**.
+
+```console
+$ git cat-file -p e060913d1a04d39082981dc116c5a5cd35ba8e52
+
+100644 blob 397b4a7624e35fa60563a9c03b1213d93f7b6546    .gitignore
+100644 blob 67f24d19be001eebf7bcdde488d8ab594bcd969d    PSScriptAnalyzerSettings.psd1
+100644 blob 4bd5bb6fcff0b514d0160f3cb8ff01b5de46eeb4    README.md
+100644 blob 207846dc4b8f93edd892df9b6058ded48f5355b8    dotfiles.ps1
+100755 blob fa9fe71978d17992a3f27eaf78f2619a25a1966d    dotfiles.sh
+040000 tree 0199c6476a45a6dadadaf7baf70a136d7f8f217f    dotfiles
+100644 blob b6e1531298fed5dc7a019f6c01018b5c1add3c99    flake.lock
+100644 blob 92d9549668557adb021f959f8b898ad96ee84efb    flake.nix
+100644 blob bb166d071cb8541aac7df35b7c1f5dbf420dd70c    home.nix
+100644 blob baa979aff962214ddb5e23502acdb211d8d32064    install.ps1
+040000 tree c1aef838a425cd6f209ecc01f28bef2208fd2d26    packages
+```
+
+You can either go deeper to the nested `tree` or inspect the snapshot content of a `blob` using the same way.
+
+```console
+$ git cat-file -p 67f24d19be001eebf7bcdde488d8ab594bcd969d
+
+@{
+    IncludeRules = @('PSAvoidTrailingWhitespace')
+}
+```
+
+## Checkout Commit
+
+

docs/document/Skill/Git/docs/3.Git History & Reset.md

@@ -0,0 +1,26 @@
+# Git History & Reset
+
+- `git log`: commit logs that can be synchronized with remotes.
+- `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.
+
+## Commit History Query
+
+- `-<n>`: limits count of commit logs
+- `--skip=<n>`: skip count
+- ..., see: `git help log` in *Commit Limiting* section
+
+### History Exclusion
+
+Use `^` to exclude commits from certain points, such as `git log ^main foo` to exclude commits from `main` but keep commits from `foo`.
+
+Example: show commits within branch `pwsh_es` but not in `master`:
+```console
+$ git log ^master pwsh_es
+* e8284ebb96d8 (origin/pwsh_es, pwsh_es) maintainers: add sharpchen
+* c0c964d8ae68 powershell-editor-services: init at 4.1.0
+
+$ git log master..pwsh_es
+* e8284ebb96d8 (origin/pwsh_es, pwsh_es) maintainers: add sharpchen
+* c0c964d8ae68 powershell-editor-services: init at 4.1.0
+```

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

@@ -0,0 +1,42 @@
+# 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
+
+- branch name
+- `@{upstream}` or `@{u}`: refer to the local upstream
+
+## 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
+
+### Fast-Forward & Three-way Merging
+
+

docs/document/Skill/PowerShell/docs/Language/Array.md

@@ -32,11 +32,11 @@ $foo = @() # empty array
 >
 >$(1,2,3).Length # 3 this has different semantic but with same result
 >
->(,(1,2,3)).Length # 3 # does spread items # [!code highlight] 
+>(,(1,2,3)).Length # 3 # does spread items # [!code highlight]
 >
->(,@(1,2,3)).Length # 1 # does not spread items # [!code highlight] 
+>(,@(1,2,3)).Length # 1 # does not spread items # [!code highlight]
 >
->((gci), (gci ..)).Length # 2 # [!code highlight] 
+>((gci), (gci ..)).Length # 2 # [!code highlight]
 > ```
 
 ### From Expression and Statement
@@ -72,15 +72,15 @@ $foo = @{
     Age = 18
 }
 
-@($foo.GetEnumerator()).Length # 2, System.Collections.DictionaryEntry from the HashTable # [!code highlight] 
+@($foo.GetEnumerator()).Length # 2, System.Collections.DictionaryEntry from the HashTable # [!code highlight]
 ```
 
 ### From Range
 
 Range operator can create array from integer range and character range inclusively from both sides.
 
 > [!NOTE]
-> character range was added in PowerShell 6 
+> character range was added in PowerShell 6
 
 ```ps1
 1..10 # 1 to 10 inclusively
@@ -128,7 +128,7 @@ Use `*` to repeat the array content for certain times.
 ((1,2,3) * 3).Length # 9
 ```
 
-A pratical usage of repetition is initialization with same value to the whole array.
+A practical usage of repetition is initialization with same value to the whole array.
 
 ```ps1
 @(255) * 100 # Fill up array sized 100 with 255 to all elements
@@ -165,9 +165,9 @@ Separate different ranges by `+` to generate a range union.
 (1..10)[0..2+4..5+7]
 ```
 
-## Substration
+## Subtraction
 
-To substract a collection from another collection, you can certainly use `LINQ` or use a simple pipeline.
+To subtract a collection from another collection, you can certainly use `LINQ` or use a simple pipeline.
 
 ```ps1
 @(1,2,3) | where { @(1, 2) -notcontains $_ } # 3
@@ -204,7 +204,7 @@ $arr = 1,2,3
 
 $arr -eq $null # empty array
 
-$null -eq $arr # False, the result we expected # [!code highlight] 
+$null -eq $arr # False, the result we expected # [!code highlight]
 ```
 
 > [!TIP]
@@ -247,7 +247,7 @@ Keyword operators has special functionalities on collections.
 
 ```ps1
 $a, $b, $c = 1,2,3 # $a = 1, $b = 2, $c = 3
-$a, $b = 1,2,3 # $a = 1, $b = 3 This might not be expected # [!code warning] 
+$a, $b = 1,2,3 # $a = 1, $b = 3 This might not be expected # [!code warning]
 ```
 
 > [!WARNING]