From dfc62c4a9ee276ef1c02aca8a30bf4ca1665642e Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:07:34 +0200
Subject: [PATCH 01/21] Add a 1 line description at the top of README.md

---
 README.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index d48c1cd..2df209c 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,16 @@
 # git-artifact
 
+> Effortless artifact management using Git repositories - seamlessly store, version, and retrieve build artifacts with automated workflows, complete traceability, and simplified DevOps pipelines.
+
 ## The rational for storing artifacts in git
 
 I have, over the years in the embbeded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace
 has slowed down turn around time for developers and CI system. Git is a fantastic zipper it self and you get integrity of workspaces for free.
 
-Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distrubuted architecture. `git-artifact` makes sure this problem is handled by storing commits "horisontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git: 
+Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distrubuted architecture. `git-artifact` makes sure this problem is handled by storing commits "horizontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git:
+
 - Firstly; You can garbage collect intermidiate artifacts by just deleting the tag
-- Secondly; You only fetch what you need - even without using shallow. 
+- Secondly; You only fetch what you need - even without using shallow.
 
 ### CI/CD integration
 
@@ -40,7 +43,7 @@ A few remarks, aspects and thoughts when retrieving the artifacts
 
 Git normally stacks the history hence you cannot delete commit in the middle of the history. `git-artifact` make a "horizontal" history - i.e the commits are not stacked on top of each other, but next to each other.
 
-The history of git-artifact workflow can basically look like this: 
+The history of git-artifact workflow can basically look like this:
 
 ``` mermaid
 %%{init: { 
@@ -73,9 +76,7 @@ gitGraph:
    checkout latest-2.0
    commit id: "2.0/src" tag: "2.0/src"
    commit id: "2.0/test" tag: "2.0/test"
-``` 
-
-
+```
 
 ### Prerequisites
 

From 2f58246511f46721bf259dcbb7b1b10b29308266 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:18:21 +0200
Subject: [PATCH 02/21] Add a 1 line description at the top of README.md

---
 README.md | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index 2df209c..5068b16 100644
--- a/README.md
+++ b/README.md
@@ -1,13 +1,13 @@
-# git-artifact
+# git-artifact 🚀📦
 
-> Effortless artifact management using Git repositories - seamlessly store, version, and retrieve build artifacts with automated workflows, complete traceability, and simplified DevOps pipelines.
+> Effortless artifact management using Git repositories
 
-## The rational for storing artifacts in git
+## The rationale for storing artifacts in git
 
-I have, over the years in the embbeded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace
-has slowed down turn around time for developers and CI system. Git is a fantastic zipper it self and you get integrity of workspaces for free.
+I have, over the years in the embedded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace
+has slowed down turnaround time for developers and CI system. Git is a fantastic zipper it self and you get integrity of workspaces for free.
 
-Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distrubuted architecture. `git-artifact` makes sure this problem is handled by storing commits "horizontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git:
+Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distributed architecture. `git-artifact` makes sure this problem is handled by storing commits "horizontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git:
 
 - Firstly; You can garbage collect intermidiate artifacts by just deleting the tag
 - Secondly; You only fetch what you need - even without using shallow.
@@ -80,7 +80,7 @@ gitGraph:
 
 ### Prerequisites
 
-The tool uses tags hence the producer need to tag push-rights. It is also beneficial to have tag delete-rights to clean old artifacts. 
+The tool uses tags hence the producer need to tag push-rights. It is also beneficial to have tag delete-rights to clean old artifacts.
 
 It can also run in branch mode. It can  maintain a `latest` branch which needs to be force pushed or delete + push rights. The concept is similar to docker concept of `<image>/latest`. It is only important if you want to use tracking branches without using `git-artifact`. It could be in context of `submodules` or `repo manifests`.
 

From c1aece227f392c3a256eec459349dbf84229efad Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:20:25 +0200
Subject: [PATCH 03/21] Update README.md to enhance clarity on benefits and
 rationale for using git-artifact

---
 README.md | 13 ++++++++++---
 1 file changed, 10 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 5068b16..5ffa360 100644
--- a/README.md
+++ b/README.md
@@ -2,6 +2,16 @@
 
 > Effortless artifact management using Git repositories
 
+## Why?
+
+- Seamlessly store, version, and retrieve build artifacts with the power of Git
+- Automate artifact workflows, ensure traceability, and simplify DevOps pipelines
+
+## Benefits
+
+- You can garbage collect intermediate artifacts by just deleting the tag
+- You only fetch what you need - even without using shallow.
+
 ## The rationale for storing artifacts in git
 
 I have, over the years in the embedded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace
@@ -9,9 +19,6 @@ has slowed down turnaround time for developers and CI system. Git is a fantastic
 
 Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distributed architecture. `git-artifact` makes sure this problem is handled by storing commits "horizontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git:
 
-- Firstly; You can garbage collect intermidiate artifacts by just deleting the tag
-- Secondly; You only fetch what you need - even without using shallow.
-
 ### CI/CD integration
 
 Triggering of new builds or tests are done the normal way as known from triggering your pipelines of source code - push or pull - simple..

From ccbab0bc884cfe5542e37415e4b500065384a7ed Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:20:50 +0200
Subject: [PATCH 04/21] Update the 1 line description at the top of the
 git-artifact

---
 git-artifact | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/git-artifact b/git-artifact
index 58a38cb..8bac4c3 100755
--- a/git-artifact
+++ b/git-artifact
@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 #
-# git-artifact: use a git repository as artifact management storage
+# git-artifact: Effortless Artifact Management Using Git
 #
 
 function check_environment() {

From a13c0b3ec66a07f6e1bad64b3aee75a11f9368bd Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:21:21 +0200
Subject: [PATCH 05/21] minor linting in git-artifact and _tests.sh

---
 _tests.sh    | 15 ++++++++-------
 git-artifact | 23 ++++++++---------------
 2 files changed, 16 insertions(+), 22 deletions(-)

diff --git a/_tests.sh b/_tests.sh
index 1f82482..c09fd0b 100755
--- a/_tests.sh
+++ b/_tests.sh
@@ -68,7 +68,7 @@ function generate_base_repo() {
         git init --bare $remote_tester_repo
         git -C $remote_tester_repo symbolic-ref HEAD refs/heads/${default_branch:-main}
     }
-    git artifact init --url="$(pwd)/$remote_tester_repo" --path $local_tester_repo -b ${default_branch:-main} 
+    git artifact init --url="$(pwd)/$remote_tester_repo" --path $local_tester_repo -b ${default_branch:-main}
     cd $local_tester_repo
     touch test.txt
     git artifact add-n-push -t v1.0
@@ -138,7 +138,7 @@ eval_testcase
 test="4"
 testcase_synopsis="base-repo ; clone; add-n-push with branch"
 testcase_header
-{ 
+{
     cd $test
     generate_base_repo
     git artifact clone --url=$(pwd)/$remote_tester_repo -b latest --path $clone_tester_repo
@@ -153,7 +153,7 @@ eval_testcase
 test="5"
 testcase_synopsis="base-repo ; clone; fetch-co-latest pattern"
 testcase_header
-{ 
+{
     cd $test
     generate_base_repo
     sleep 1
@@ -186,7 +186,7 @@ eval_testcase
 test="5.1"
 testcase_synopsis="base-repo ; clone; find-latest pattern"
 testcase_header
-{ 
+{
     cd $test
     generate_base_repo
     sleep 1
@@ -200,7 +200,7 @@ eval_testcase
 test="6"
 testcase_synopsis="base-repo ; clone; fetch-tags"
 testcase_header
-{ 
+{
     cd $test
     generate_base_repo
     git artifact clone --url=$(pwd)/$remote_tester_repo -b latest --path $clone_tester_repo
@@ -235,6 +235,7 @@ else
     echo "Some tests failed. - List of logs:"
     find . -name run.log -o -name nok.log | sort
     echo
-fi  
+fi
+
 # Exit with the global exit code
-exit $global_exit_code
\ No newline at end of file
+exit $global_exit_code
diff --git a/git-artifact b/git-artifact
index 8bac4c3..ea3eace 100755
--- a/git-artifact
+++ b/git-artifact
@@ -45,7 +45,6 @@ function check_git_environment() {
         echo >&2 "   not as \`$basename\`." >&2
         exit 126
     fi
-
 }
 
 function show_info() {
@@ -85,20 +84,20 @@ h,help          show the help
 q               quiet
 d               show debug messages
 
- options for 'init' and 'clone'
+options for 'init' and 'clone'
 u,url=        the remote url
 p,path=       the optional path for init and clone 
 
- options for 'init', 'clone', 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
+options for 'init', 'clone', 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
 b,branch=     use branch for local changes and pushes
 
- options for 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
+options for 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
 t,tag=         the tag to be created
 
- options for 'fetch-co-latest', 'find-latest'
+options for 'fetch-co-latest', 'find-latest'
 r,regex=       the reg-ex pattern to latest of
 
- options for 'fetch-tags'
+options for 'fetch-tags'
 s,sha1=       The sha1 of which to get tags from from 
 "
 }
@@ -110,7 +109,6 @@ debug () {
     fi
 }
 
-
 set_repo_dir() {
     local -n _ref_dir=${1}
     if [[ $arg_path != ""  ]]; then
@@ -149,7 +147,7 @@ set_remote_default_branch() {
     _ref_remote_default_branch=$(git ls-remote --symref "$arg_remoteurl" HEAD | grep -E 'ref:[[:space:]].+[[:space:]]HEAD' | cut -f 1 | cut -d '/' -f 3-)
     
     if [[ -n ${_ref_remote_default_branch:-} ]]; then 
-	    echo "Found: ${_ref_remote_default_branch}"
+        echo "Found: ${_ref_remote_default_branch}"
     else
         local _base_branch=
         set_base_branch _base_branch
@@ -181,8 +179,8 @@ cmd_init() {
     set_base_branch _base_branch
 
     git init -b "${_base_branch}" "$_dir" || {
-         git init "$_dir"
-         git -C "$_dir" switch -C "${_base_branch}"
+        git init "$_dir"
+        git -C "$_dir" switch -C "${_base_branch}"
     }
     cd "$_dir"
     git_local_config
@@ -215,7 +213,6 @@ cmd_init() {
 }
 
 cmd_clone() {
-
     local _dir=
     set_repo_dir _dir
     
@@ -281,10 +278,8 @@ cmd_push(){
     git log -2 --oneline --decorate --graph --all
 
     echo "All good.. get back to clear state for next artifact..."
-    
 }
 
-
 cmd_add-n-push() {
     cmd_add-n-tag
     cmd_push
@@ -352,7 +347,6 @@ cmd_find-latest() {
     printf "%s\n" "$__latest_tag"
 }
 
-
 cmd_fetch-co-latest() {
     latest_tag=""
     find-latest latest_tag
@@ -360,7 +354,6 @@ cmd_fetch-co-latest() {
     git checkout $latest_tag
 }
 
-
 cmd_fetch-tags() {
     echo "Getting tags from: $arg_sha1"
     tags=$(git ls-remote --tags origin | grep '\^{}' | grep -E "^${arg_sha1}" | cut  -f2 | cut -d ^ -f 1) || tags=""

From 9da1e4086dc61db3a92867fe738e1dd7ebad1c60 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:25:23 +0200
Subject: [PATCH 06/21] Refactor the first 2 sections in README.md to answer
 the 2 questions a new onlooker would ask

---
 README.md | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 5ffa360..91016cb 100644
--- a/README.md
+++ b/README.md
@@ -2,22 +2,19 @@
 
 > Effortless artifact management using Git repositories
 
-## Why?
+## Why use `git-artifact`?
 
-- Seamlessly store, version, and retrieve build artifacts with the power of Git
-- Automate artifact workflows, ensure traceability, and simplify DevOps pipelines
+`git-artifact` brings artifact management directly into your Git workflow, making it easy to store, version, and retrieve build artifacts without extra infrastructure.
 
-## Benefits
+### Key Benefits
 
-- You can garbage collect intermediate artifacts by just deleting the tag
-- You only fetch what you need - even without using shallow.
+- **Seamless integration:** Manage artifacts alongside your source code using familiar Git tools.
+- **Efficient storage:** Artifacts are stored as independent commits, so you fetch only what you need.
+- **Traceability & integrity:** Tags and Git’s checksums provide clear versioning and authenticity.
+- **Easy cleanup:** Remove intermediate artifacts by simply deleting their tags.
+- **Unified workflow:** Eliminate the need for separate artifact repositories or complex tools.
 
-## The rationale for storing artifacts in git
-
-I have, over the years in the embedded enterprise industry, constantly come across many scenarios where zipping, downloading and unzipping generic dependencies and maintaining workspace
-has slowed down turnaround time for developers and CI system. Git is a fantastic zipper it self and you get integrity of workspaces for free.
-
-Git has always been mentioned to be bad for storing artifacts due to the block chain technology and distributed architecture. `git-artifact` makes sure this problem is handled by storing commits "horizontally" using tags rather than the default "stacked" way. It gives a few advantages compared to standard usage of git:
+Whether for embedded, enterprise, or CI/CD environments, `git-artifact` streamlines artifact management by making it a natural extension of your existing Git processes.
 
 ### CI/CD integration
 

From 8c54b513e2faeda84d2b8a5d2c69f5dcf87b1d6e Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Mon, 28 Jul 2025 23:39:22 +0200
Subject: [PATCH 07/21] Remove a second from README.md as it is now included in
 the Benefits section.

---
 README.md | 8 --------
 1 file changed, 8 deletions(-)

diff --git a/README.md b/README.md
index 91016cb..977806b 100644
--- a/README.md
+++ b/README.md
@@ -16,14 +16,6 @@
 
 Whether for embedded, enterprise, or CI/CD environments, `git-artifact` streamlines artifact management by making it a natural extension of your existing Git processes.
 
-### CI/CD integration
-
-Triggering of new builds or tests are done the normal way as known from triggering your pipelines of source code - push or pull - simple..
-
-### Save money
-
-You can save additional license and maintainance cost and/or coqnative load by maintaining and using an additional system for artifacts. You can handle it with your current git repository manager.
-
 ### Producer of artifacts
 
 A few remarks, aspects and thoughts when storing the artifacts

From 916d4ae1c4ae30f0a00998be5ba1ca6d3aeb389e Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 00:53:13 +0200
Subject: [PATCH 08/21] Update the structure of README.md to get into how to
 use it faster

---
 README.md | 213 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 122 insertions(+), 91 deletions(-)

diff --git a/README.md b/README.md
index 977806b..f0f2efe 100644
--- a/README.md
+++ b/README.md
@@ -6,6 +6,22 @@
 
 `git-artifact` brings artifact management directly into your Git workflow, making it easy to store, version, and retrieve build artifacts without extra infrastructure.
 
+### Super simple
+
+To push artifacts:
+
+- `git artifact init` to set up a new repository for artifact management.
+- Add files (e.g., binaries, libraries) directly to the repository without zipping or archiving.
+- Use `git artifact add-n-push` to commit and push artifacts with a tag, like `v1.0`, ensuring they are versioned and easily retrievable.
+
+To retrieve artifacts:
+
+- `git artifact clone` to clone the repository.
+- Use `git artifact find-latest -r 'v*.*'` to search for the latest version of an artifact.
+- Use `git artifact fetch-co-latest --regex 'v*.*'` to download and checkout the latest artifact version, files are ready to use!
+
+No external tools or complex configurations are needed. `git-artifact` leverages Git's powerful version control features to manage artifacts as if they were part of your source code.
+
 ### Key Benefits
 
 - **Seamless integration:** Manage artifacts alongside your source code using familiar Git tools.
@@ -16,120 +32,71 @@
 
 Whether for embedded, enterprise, or CI/CD environments, `git-artifact` streamlines artifact management by making it a natural extension of your existing Git processes.
 
-### Producer of artifacts
-
-A few remarks, aspects and thoughts when storing the artifacts
-
-- easy to append artifacts as stages evolves with more artifacts
-- no need to zip before upload - just commit as the artifact should be used.
-- easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction
-- add the source code as a dependency to the artifact. It will then be easy restore the source for diff and debugging
-
-### Consumer of the artifacts
-
-A few remarks, aspects and thoughts when retrieving the artifacts
-
-- The consumer do not need anything than standard git
-- Pipelines just consumes the artifact unzip and ready to use as they were produced
-- Use your favorit git dependency system like submodules(this is the correct way for submodule usage btw ), repo tool or ..
-- Even a consumer can be a producer by adding further artifacts on top the consumed commit with a new commit and tag
-- git understand the content in workspace and git clean does not remove artifacts in contrast to downloaded artifacts
+## How to use `git-artifact`
 
-## How is it done
+### Install git-artifact
 
-Git normally stacks the history hence you cannot delete commit in the middle of the history. `git-artifact` make a "horizontal" history - i.e the commits are not stacked on top of each other, but next to each other.
+To install `git-artifact`, simply download or clone this repository and ensure the script is available in your `PATH`. Once in your `PATH`, `git` will automatically recognize `git-artifact` as a native subcommand (`git artifact`), seamlessly extending your Git functionality.
 
-The history of git-artifact workflow can basically look like this:
+Or quickly install `git-artifact` by running:
 
-``` mermaid
-%%{init: { 
-    'gitGraph': {
-        'loglevel' : 'debug',
-        'orientation': 'vertical', 
-        'showCommitLabel': true, 
-        'showBranches': false
-    }} }%%
-gitGraph:
-   commit id: "init" tag: "init" type:  HIGHLIGHT
-   branch latest-1.0 order: 2
-   branch latest-1.1 order: 3
-   branch latest-1.2 order: 4
-   branch latest-2.0 order: 5
-   checkout latest-1.0
-   commit id: "1.0/bin" tag: "1.0/bin"
-   commit id: "1.0/src" tag: "1.0/src"
-   checkout latest-1.1
-   commit id: "1.1/bin" tag: "1.1/bin"
-   checkout latest-1.2
-   commit id: "1.2/bin" tag: "1.2/bin"
-   checkout latest-2.0
-   commit id: "2.0/bin" tag: "2.0/bin"
-   checkout main
-   commit id: "update scripts" tag: "main" type:  HIGHLIGHT
-   branch foo order: 1
-   checkout foo
-   commit id: "3.0/bin" tag: "3.0/bin"
-   checkout latest-2.0
-   commit id: "2.0/src" tag: "2.0/src"
-   commit id: "2.0/test" tag: "2.0/test"
+```bash
+mkdir -p ~/.local/bin && curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact
 ```
 
-### Prerequisites
-
-The tool uses tags hence the producer need to tag push-rights. It is also beneficial to have tag delete-rights to clean old artifacts.
+Make sure `~/.local/bin` is included in your `PATH` environment variable:
 
-It can also run in branch mode. It can  maintain a `latest` branch which needs to be force pushed or delete + push rights. The concept is similar to docker concept of `<image>/latest`. It is only important if you want to use tracking branches without using `git-artifact`. It could be in context of `submodules` or `repo manifests`.
-
-### Installation
-
-Download or clone this repo (`git-artifact`) and add make it available in the PATH. Given that `git-artifact` is in the PATH, then `git` can use it as an command like `git artifact`. It is now integrated with git and git is extended.
+```bash
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
+```
 
-## Getting started
+Now you can use `git artifact` as a regular Git command.
 
-First you need to create a repository in your git repository manager. You can either choose to initialize the repo, but `git artifact` also have command to do that and it states that this repository is "special" repository containing git artifacts.
+### Create a test repository
 
-### Initialize the repository
+- Create a repo, for example on GitHub: [https://github.com/new?name=test-git-artifact]
 
-Let us now initialized a repo:
+- Use the `git artifact init` command to initialize a new repository locally for managing artifacts.
 
 ```bash
-git artifact init --url=<remote_url> --path my-git-artifact-path
+# replace `__USERNAME__` with your GitHub username
+git artifact init --url=git@github.com:__USERNAME__/test-git-artifact.git --path test-git-artifact
 ```
 
 ### Add the artifact
 
-The repository and path initialize above ready to use. Copy the artifacts to your path in the folder structure the "constumer" desire it. There is not reason to tar or zip it. Git will handling this for optimized storage and easiness.
+Copy the artifacts to your path in the folder structure the "consumer" desire it. There is not reason to tar or zip it. Git will handling this for optimized storage and easiness.
 
 ```bash
-cd my-git-artifact-path
-cp -rf <build-dir>/my.lib /include .
+cd test-git-artifact
+touch artifact-1.0
+# cp -rf <build-dir>/my.lib /include .
 git artifact add-n-push -t v1.0
 ```
 
-The artifact v1.0 is now commited, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository. It is now ready to make a new artifact based on the default branched
+Voila! The artifact v1.0 is now commited, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository. It is now ready to make a new artifact based on the default branched
 
-## Finding and getting artifacts
-
-Firstly clone the git artifact repository. Note that you only clone and get the default branch
+### Finding and getting artifacts
 
 ```bash
-git artifact clone --url=<remote> --path my-git-artifact-path
-cd my-git-artifact-path
-````
-
-### Find the latest using pattern
+# You can use the `git artifact clone` command to clone a repository and set it up for artifact management. Note that you only clone and get the default branch!
+git artifact clone --url=git@github.com:__USERNAME__/test-git-artifact.git --path test-git-artifact
+cd test-git-artifact
+```
 
 ```bash
+# Find the latest using pattern
 git artifact find-latest -r 'v*.*'
 ```
 
-### Download and checkout the latest
-
 ```bash
+# Download and checkout the latest
 git artifact fetch-co-latest --regex 'v*.*'
 ```
 
-## Appending to an artifact
+## Advanced
+
+### Appending to an artifact
 
 You can append to an artifact with advantage. Let say you create a library and you run a lot of tests in a later stage and the result is a test report. You can then just add that on top of the library tag.  
 
@@ -145,22 +112,12 @@ vX.Y.Z/src
 vX.Y.Z/lib
 ```
 
-### Add the source code that was used to build the artifact
+#### Add the source code that was used to build the artifact
 
 The source code in many companies and open-source projects are free to view, debug and edit. You can make it easy accessable by adding the source code as submodule and sha1 in to the artifact history. It sounds odd, but it gives the developers easy access to checkout the correct version that was used to build artifact.
 
 This way it actually possible to create a full block-chain of everything that was involved in producing a product.
 
-## Add information to the annotated tag
-
-TODO: option for file or string
-
-## Pruning / cleaning artifacts
-
-TODO: based on count..
-
-## Advanced
-
 ### LFS
 
 `git artifact` work great out of the box without any extensions like LFS. It can though still be interesting to commit an `git-lfs` configuration to the default branch
@@ -182,3 +139,77 @@ This way is like promotion in normal artifact managemnet systems, where you prom
 #### Using same repository
 
 This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be append on top if a release candidate tag.
+
+### Add information to the annotated tag
+
+TODO: option for file or string
+
+### Pruning / cleaning artifacts
+
+TODO: based on count..
+
+## Notes
+
+### Permissions needed
+
+`git-artifact` relies on Git tags for artifact management. As a producer, you need permission to create and push tags to the remote repository. To effectively manage and clean up old artifacts, having permission to delete tags is also recommended.
+
+Alternatively, `git-artifact` can operate in branch mode, maintaining a `latest` branch to track the most recent artifact. This requires force-push or delete-and-push rights for the branch. The approach is similar to Docker’s `<image>:latest` tag and is useful if you want to use tracking branches outside of `git-artifact`—for example, with Git submodules or repo manifests.
+
+### Producer of artifacts
+
+A few remarks, aspects and thoughts when storing the artifacts
+
+- easy to append artifacts as stages evolves with more artifacts
+- no need to zip before upload - just commit as the artifact should be used.
+- easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction
+- add the source code as a dependency to the artifact. It will then be easy restore the source for diff and debugging
+
+### Consumer of the artifacts
+
+A few remarks, aspects and thoughts when retrieving the artifacts
+
+- The consumer do not need anything than standard git
+- Pipelines just consumes the artifact unzip and ready to use as they were produced
+- Use your favorit git dependency system like submodules(this is the correct way for submodule usage btw ), repo tool or ..
+- Even a consumer can be a producer by adding further artifacts on top the consumed commit with a new commit and tag
+- git understand the content in workspace and git clean does not remove artifacts in contrast to downloaded artifacts
+
+### How is it done
+
+Git normally stacks the history hence you cannot delete commit in the middle of the history. `git-artifact` make a "horizontal" history - i.e the commits are not stacked on top of each other, but next to each other.
+
+The history of git-artifact workflow can basically look like this:
+
+``` mermaid
+%%{init: { 
+    'gitGraph': {
+        'loglevel' : 'debug',
+        'orientation': 'vertical', 
+        'showCommitLabel': true, 
+        'showBranches': false
+    }} }%%
+gitGraph:
+   commit id: "init" tag: "init" type:  HIGHLIGHT
+   branch latest-1.0 order: 2
+   branch latest-1.1 order: 3
+   branch latest-1.2 order: 4
+   branch latest-2.0 order: 5
+   checkout latest-1.0
+   commit id: "1.0/bin" tag: "1.0/bin"
+   commit id: "1.0/src" tag: "1.0/src"
+   checkout latest-1.1
+   commit id: "1.1/bin" tag: "1.1/bin"
+   checkout latest-1.2
+   commit id: "1.2/bin" tag: "1.2/bin"
+   checkout latest-2.0
+   commit id: "2.0/bin" tag: "2.0/bin"
+   checkout main
+   commit id: "update scripts" tag: "main" type:  HIGHLIGHT
+   branch foo order: 1
+   checkout foo
+   commit id: "3.0/bin" tag: "3.0/bin"
+   checkout latest-2.0
+   commit id: "2.0/src" tag: "2.0/src"
+   commit id: "2.0/test" tag: "2.0/test"
+```

From a065190ff4dd90741b2b3f3a8746246fc62bbdf3 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 00:53:26 +0200
Subject: [PATCH 09/21] Use copilot to proof read the README.md file

---
 README.md | 54 +++++++++++++++++++++++++++---------------------------
 1 file changed, 27 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index f0f2efe..76de988 100644
--- a/README.md
+++ b/README.md
@@ -65,7 +65,7 @@ git artifact init --url=git@github.com:__USERNAME__/test-git-artifact.git --path
 
 ### Add the artifact
 
-Copy the artifacts to your path in the folder structure the "consumer" desire it. There is not reason to tar or zip it. Git will handling this for optimized storage and easiness.
+Copy the artifacts to your path in the folder structure the "consumer" desires. There is no reason to tar or zip it. Git will handle this for optimized storage and ease of use.
 
 ```bash
 cd test-git-artifact
@@ -74,7 +74,7 @@ touch artifact-1.0
 git artifact add-n-push -t v1.0
 ```
 
-Voila! The artifact v1.0 is now commited, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository. It is now ready to make a new artifact based on the default branched
+Voila! The artifact v1.0 is now committed, pushed _and_ importantly - the workspace is set back to the default branch of the remote repository. It is now ready to make a new artifact based on the default branch.
 
 ### Finding and getting artifacts
 
@@ -98,12 +98,12 @@ git artifact fetch-co-latest --regex 'v*.*'
 
 ### Appending to an artifact
 
-You can append to an artifact with advantage. Let say you create a library and you run a lot of tests in a later stage and the result is a test report. You can then just add that on top of the library tag.  
+You can append to an artifact advantageously. Let's say you create a library and you run a lot of tests at a later stage and the result is a test report. You can then just add that on top of the library tag.  
 
 - Download and checkout the artifact ( see above )
 - Add a new artifact ( see above )
 
-You should of course consider this in your naming convension. Consider something like this:
+You should of course consider this in your naming convention. Consider something like this:
 
 ```bash
 vX.Y.Z/release-note
@@ -114,31 +114,31 @@ vX.Y.Z/lib
 
 #### Add the source code that was used to build the artifact
 
-The source code in many companies and open-source projects are free to view, debug and edit. You can make it easy accessable by adding the source code as submodule and sha1 in to the artifact history. It sounds odd, but it gives the developers easy access to checkout the correct version that was used to build artifact.
+The source code in many companies and open-source projects is free to view, debug and edit. You can make it easily accessible by adding the source code as a submodule and sha1 into the artifact history. It sounds odd, but it gives developers easy access to checkout the correct version that was used to build the artifact.
 
-This way it actually possible to create a full block-chain of everything that was involved in producing a product.
+This way it is actually possible to create a full blockchain of everything that was involved in producing a product.
 
 ### LFS
 
-`git artifact` work great out of the box without any extensions like LFS. It can though still be interesting to commit an `git-lfs` configuration to the default branch
+`git artifact` works great out of the box without any extensions like LFS. It can though still be interesting to commit a `git-lfs` configuration to the default branch
 
-- Artifact sets that can many common binary/large files from version to version will then be able to detect that it already have have this file in the LFS storage and do not have to fetch/push it again.
-- You can download all tags without checkout and then you can search for meta-data in the annotated tags without suffering large data transfer and storage in order to clean.
+- Artifact sets that contain many common binary/large files from version to version will then be able to detect that they already have this file in the LFS storage and do not have to fetch/push it again.
+- You can download all tags without checkout and then you can search for metadata in the annotated tags without suffering large data transfer and storage in order to clean up.
 
 ### Promotions
 
-There are genrally default two ways to you can do promotions.
-Building new artifacts for the release is like a new artifact using the above patterns, which can either be a new or appended artifacts.
+There are generally two default ways you can do promotions.
+Building new artifacts for the release is like creating a new artifact using the above patterns, which can either be a new or appended artifact.
 
-Promotion decision should also be seen in connection related to pruning of tag which is not valid of any interest anymore. It should be simple and easy to prune without fear of deleting tags that should not be deleted
+Promotion decisions should also be seen in connection to pruning of tags which are no longer valid or of any interest. It should be simple and easy to prune without fear of deleting tags that should not be deleted.
 
 #### Using different repository
 
-This way is like promotion in normal artifact managemnet systems, where you promote to from one project/repository to another. You basically download the tag from the original repository and then push the tag to promotion reposity. This way you can control access and keep different URL's for candidates and releases.
+This way is like promotion in normal artifact management systems, where you promote from one project/repository to another. You basically download the tag from the original repository and then push the tag to the promotion repository. This way you can control access and keep different URLs for candidates and releases.
 
 #### Using same repository
 
-This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be append on top if a release candidate tag.
+This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be appended on top of a release candidate tag.
 
 ### Add information to the annotated tag
 
@@ -158,28 +158,28 @@ Alternatively, `git-artifact` can operate in branch mode, maintaining a `latest`
 
 ### Producer of artifacts
 
-A few remarks, aspects and thoughts when storing the artifacts
+A few remarks, aspects and thoughts when storing artifacts:
 
-- easy to append artifacts as stages evolves with more artifacts
-- no need to zip before upload - just commit as the artifact should be used.
-- easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction
-- add the source code as a dependency to the artifact. It will then be easy restore the source for diff and debugging
+- Easy to append artifacts as stages evolve with more artifacts
+- No need to zip before upload - just commit as the artifact should be used
+- Easy to add information, environment, tools and git source sha1 in the artifact for traceability and later reproduction
+- Add the source code as a dependency to the artifact. It will then be easy to restore the source for diff and debugging
 
 ### Consumer of the artifacts
 
-A few remarks, aspects and thoughts when retrieving the artifacts
+A few remarks, aspects and thoughts when retrieving artifacts:
 
-- The consumer do not need anything than standard git
-- Pipelines just consumes the artifact unzip and ready to use as they were produced
-- Use your favorit git dependency system like submodules(this is the correct way for submodule usage btw ), repo tool or ..
-- Even a consumer can be a producer by adding further artifacts on top the consumed commit with a new commit and tag
-- git understand the content in workspace and git clean does not remove artifacts in contrast to downloaded artifacts
+- The consumer does not need anything other than standard git
+- Pipelines just consume the artifact unzipped and ready to use as they were produced
+- Use your favorite git dependency system like submodules (this is the correct way for submodule usage btw), repo tool or similar
+- Even a consumer can be a producer by adding further artifacts on top of the consumed commit with a new commit and tag
+- Git understands the content in workspace and git clean does not remove artifacts in contrast to downloaded artifacts
 
 ### How is it done
 
-Git normally stacks the history hence you cannot delete commit in the middle of the history. `git-artifact` make a "horizontal" history - i.e the commits are not stacked on top of each other, but next to each other.
+Git normally stacks the history; hence you cannot delete commits in the middle of the history. `git-artifact` makes a "horizontal" history - i.e., the commits are not stacked on top of each other, but next to each other.
 
-The history of git-artifact workflow can basically look like this:
+The history of the git-artifact workflow can basically look like this:
 
 ``` mermaid
 %%{init: { 

From 037e478334e37d5868b3704adaa1eff15f21a263 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 00:53:34 +0200
Subject: [PATCH 10/21] minor linting update in git-artifact

---
 git-artifact | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/git-artifact b/git-artifact
index ea3eace..5d9b1c7 100755
--- a/git-artifact
+++ b/git-artifact
@@ -225,7 +225,7 @@ cmd_clone() {
     git_local_config
 
     if [[ -e ./setup.sh ]]; then
-        echo "Setup file exists - source it"   
+        echo "Setup file exists - source it"
         # shellcheck source=/dev/null
         . ./setup.sh
     else

From 0f0b2be149ec9bf9a6650581dc0e521664fb7719 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 01:20:51 +0200
Subject: [PATCH 11/21] Replace the Super simple block with Quick Start (TL;DR)

---
 README.md | 18 ++++++------------
 1 file changed, 6 insertions(+), 12 deletions(-)

diff --git a/README.md b/README.md
index 76de988..e5add78 100644
--- a/README.md
+++ b/README.md
@@ -6,19 +6,13 @@
 
 `git-artifact` brings artifact management directly into your Git workflow, making it easy to store, version, and retrieve build artifacts without extra infrastructure.
 
-### Super simple
+## Quick Start (TL;DR)
 
-To push artifacts:
-
-- `git artifact init` to set up a new repository for artifact management.
-- Add files (e.g., binaries, libraries) directly to the repository without zipping or archiving.
-- Use `git artifact add-n-push` to commit and push artifacts with a tag, like `v1.0`, ensuring they are versioned and easily retrievable.
-
-To retrieve artifacts:
-
-- `git artifact clone` to clone the repository.
-- Use `git artifact find-latest -r 'v*.*'` to search for the latest version of an artifact.
-- Use `git artifact fetch-co-latest --regex 'v*.*'` to download and checkout the latest artifact version, files are ready to use!
+1. Install: `curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact` (Make sure `~/.local/bin` is in your `PATH`)
+2. Create repo on github: <https://github.com/new?name=test-git-artifact>
+3. Init the repo locally: `git artifact init git@github.com:__USERNAME__/test-git-artifact.git --path test-git-artifact` (replace `__USERNAME__` with your GitHub username)
+4. Add artifact: `touch artifact-1.0 && git artifact add-n-push -t v1.0`
+5. Find & Retrieve: `git artifact find-latest` & `git artifact fetch-co-latest`
 
 No external tools or complex configurations are needed. `git-artifact` leverages Git's powerful version control features to manage artifacts as if they were part of your source code.
 

From a2f96c27eba24823b80b597e4cdaa5e271b08d7d Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 01:44:30 +0200
Subject: [PATCH 12/21] Shorten the Quick Start

---
 README.md | 14 +++++---------
 1 file changed, 5 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index e5add78..ccbd03e 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,11 @@
 
 > Effortless artifact management using Git repositories
 
-## Why use `git-artifact`?
-
-`git-artifact` brings artifact management directly into your Git workflow, making it easy to store, version, and retrieve build artifacts without extra infrastructure.
-
 ## Quick Start (TL;DR)
 
-1. Install: `curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact` (Make sure `~/.local/bin` is in your `PATH`)
+1. Install binary in PATH: `curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact`
 2. Create repo on github: <https://github.com/new?name=test-git-artifact>
-3. Init the repo locally: `git artifact init git@github.com:__USERNAME__/test-git-artifact.git --path test-git-artifact` (replace `__USERNAME__` with your GitHub username)
+3. Init the repo locally (Update `_USER_`): `git artifact init git@github.com:_USER_/test-git-artifact.git --path test-git-artifact`
 4. Add artifact: `touch artifact-1.0 && git artifact add-n-push -t v1.0`
 5. Find & Retrieve: `git artifact find-latest` & `git artifact fetch-co-latest`
 
@@ -53,8 +49,8 @@ Now you can use `git artifact` as a regular Git command.
 - Use the `git artifact init` command to initialize a new repository locally for managing artifacts.
 
 ```bash
-# replace `__USERNAME__` with your GitHub username
-git artifact init --url=git@github.com:__USERNAME__/test-git-artifact.git --path test-git-artifact
+# replace `_USER_` with your GitHub username
+git artifact init --url=git@github.com:_USER_/test-git-artifact.git --path test-git-artifact
 ```
 
 ### Add the artifact
@@ -74,7 +70,7 @@ Voila! The artifact v1.0 is now committed, pushed _and_ importantly - the worksp
 
 ```bash
 # You can use the `git artifact clone` command to clone a repository and set it up for artifact management. Note that you only clone and get the default branch!
-git artifact clone --url=git@github.com:__USERNAME__/test-git-artifact.git --path test-git-artifact
+git artifact clone --url=git@github.com:_USER_/test-git-artifact.git --path test-git-artifact
 cd test-git-artifact
 ```
 

From b52a060a3131b9c0eb420f348dd9237cd1a81809 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 01:45:09 +0200
Subject: [PATCH 13/21] Move Notes section to above Advanced

---
 README.md | 108 +++++++++++++++++++++++++++---------------------------
 1 file changed, 54 insertions(+), 54 deletions(-)

diff --git a/README.md b/README.md
index ccbd03e..264d03c 100644
--- a/README.md
+++ b/README.md
@@ -84,60 +84,6 @@ git artifact find-latest -r 'v*.*'
 git artifact fetch-co-latest --regex 'v*.*'
 ```
 
-## Advanced
-
-### Appending to an artifact
-
-You can append to an artifact advantageously. Let's say you create a library and you run a lot of tests at a later stage and the result is a test report. You can then just add that on top of the library tag.  
-
-- Download and checkout the artifact ( see above )
-- Add a new artifact ( see above )
-
-You should of course consider this in your naming convention. Consider something like this:
-
-```bash
-vX.Y.Z/release-note
-vX.Y.Z/test
-vX.Y.Z/src
-vX.Y.Z/lib
-```
-
-#### Add the source code that was used to build the artifact
-
-The source code in many companies and open-source projects is free to view, debug and edit. You can make it easily accessible by adding the source code as a submodule and sha1 into the artifact history. It sounds odd, but it gives developers easy access to checkout the correct version that was used to build the artifact.
-
-This way it is actually possible to create a full blockchain of everything that was involved in producing a product.
-
-### LFS
-
-`git artifact` works great out of the box without any extensions like LFS. It can though still be interesting to commit a `git-lfs` configuration to the default branch
-
-- Artifact sets that contain many common binary/large files from version to version will then be able to detect that they already have this file in the LFS storage and do not have to fetch/push it again.
-- You can download all tags without checkout and then you can search for metadata in the annotated tags without suffering large data transfer and storage in order to clean up.
-
-### Promotions
-
-There are generally two default ways you can do promotions.
-Building new artifacts for the release is like creating a new artifact using the above patterns, which can either be a new or appended artifact.
-
-Promotion decisions should also be seen in connection to pruning of tags which are no longer valid or of any interest. It should be simple and easy to prune without fear of deleting tags that should not be deleted.
-
-#### Using different repository
-
-This way is like promotion in normal artifact management systems, where you promote from one project/repository to another. You basically download the tag from the original repository and then push the tag to the promotion repository. This way you can control access and keep different URLs for candidates and releases.
-
-#### Using same repository
-
-This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be appended on top of a release candidate tag.
-
-### Add information to the annotated tag
-
-TODO: option for file or string
-
-### Pruning / cleaning artifacts
-
-TODO: based on count..
-
 ## Notes
 
 ### Permissions needed
@@ -203,3 +149,57 @@ gitGraph:
    commit id: "2.0/src" tag: "2.0/src"
    commit id: "2.0/test" tag: "2.0/test"
 ```
+
+## Advanced
+
+### Appending to an artifact
+
+You can append to an artifact advantageously. Let's say you create a library and you run a lot of tests at a later stage and the result is a test report. You can then just add that on top of the library tag.  
+
+- Download and checkout the artifact ( see above )
+- Add a new artifact ( see above )
+
+You should of course consider this in your naming convention. Consider something like this:
+
+```bash
+vX.Y.Z/release-note
+vX.Y.Z/test
+vX.Y.Z/src
+vX.Y.Z/lib
+```
+
+#### Add the source code that was used to build the artifact
+
+The source code in many companies and open-source projects is free to view, debug and edit. You can make it easily accessible by adding the source code as a submodule and sha1 into the artifact history. It sounds odd, but it gives developers easy access to checkout the correct version that was used to build the artifact.
+
+This way it is actually possible to create a full blockchain of everything that was involved in producing a product.
+
+### LFS
+
+`git artifact` works great out of the box without any extensions like LFS. It can though still be interesting to commit a `git-lfs` configuration to the default branch
+
+- Artifact sets that contain many common binary/large files from version to version will then be able to detect that they already have this file in the LFS storage and do not have to fetch/push it again.
+- You can download all tags without checkout and then you can search for metadata in the annotated tags without suffering large data transfer and storage in order to clean up.
+
+### Promotions
+
+There are generally two default ways you can do promotions.
+Building new artifacts for the release is like creating a new artifact using the above patterns, which can either be a new or appended artifact.
+
+Promotion decisions should also be seen in connection to pruning of tags which are no longer valid or of any interest. It should be simple and easy to prune without fear of deleting tags that should not be deleted.
+
+#### Using different repository
+
+This way is like promotion in normal artifact management systems, where you promote from one project/repository to another. You basically download the tag from the original repository and then push the tag to the promotion repository. This way you can control access and keep different URLs for candidates and releases.
+
+#### Using same repository
+
+This way requires you to create a tag using a release tag pattern. The tag can either be a new unrelated tag or it can be appended on top of a release candidate tag.
+
+### Add information to the annotated tag
+
+TODO: option for file or string
+
+### Pruning / cleaning artifacts
+
+TODO: based on count..

From 4101643ee95df741ff8269add9831b39d4b07632 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 01:48:57 +0200
Subject: [PATCH 14/21] Fix the git artifact init command and cd into the
 folder afterwards

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 264d03c..91ccef7 100644
--- a/README.md
+++ b/README.md
@@ -6,7 +6,7 @@
 
 1. Install binary in PATH: `curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact`
 2. Create repo on github: <https://github.com/new?name=test-git-artifact>
-3. Init the repo locally (Update `_USER_`): `git artifact init git@github.com:_USER_/test-git-artifact.git --path test-git-artifact`
+3. Init the repo locally (Update `_USER_`): `git artifact init --url=git@github.com:_USER_/test-git-artifact.git --path test-git-artifact && cd test-git-artifact`
 4. Add artifact: `touch artifact-1.0 && git artifact add-n-push -t v1.0`
 5. Find & Retrieve: `git artifact find-latest` & `git artifact fetch-co-latest`
 

From 5073a919be5238686dcba60783d675ba6c2bb971 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 02:06:42 +0200
Subject: [PATCH 15/21] Update the install git-artifact section in the README

---
 README.md | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/README.md b/README.md
index 91ccef7..9fb1513 100644
--- a/README.md
+++ b/README.md
@@ -37,9 +37,21 @@ mkdir -p ~/.local/bin && curl -o ~/.local/bin/git-artifact https://raw.githubuse
 Make sure `~/.local/bin` is included in your `PATH` environment variable:
 
 ```bash
+# For bash users
 echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
 ```
 
+```zsh
+# For zsh users
+echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
+```
+
+```bash
+# Verify installation
+git artifact -h
+# Note: Use -h instead of --help (--help looks for a man page which isn't installed)
+```
+
 Now you can use `git artifact` as a regular Git command.
 
 ### Create a test repository

From 1710f3840939336b18807ca92cb5f1abb82d19d8 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 02:26:02 +0200
Subject: [PATCH 16/21] Update Quick Start (TL;DR) section to be a code block
 that can be copy pasted

---
 README.md | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 9fb1513..240f89b 100644
--- a/README.md
+++ b/README.md
@@ -4,11 +4,26 @@
 
 ## Quick Start (TL;DR)
 
-1. Install binary in PATH: `curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact`
-2. Create repo on github: <https://github.com/new?name=test-git-artifact>
-3. Init the repo locally (Update `_USER_`): `git artifact init --url=git@github.com:_USER_/test-git-artifact.git --path test-git-artifact && cd test-git-artifact`
-4. Add artifact: `touch artifact-1.0 && git artifact add-n-push -t v1.0`
-5. Find & Retrieve: `git artifact find-latest` & `git artifact fetch-co-latest`
+```bash
+# 1. Install git-artifact binary in your PATH
+curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact
+
+# 2. Create a new repository on GitHub (open this URL in your browser)
+open https://github.com/new?name=test-git-artifact
+
+echo "Press Enter after creating the repository..." && read
+
+# 3. Initialize the repository locally (replace _USER_ with your GitHub username)
+git artifact init --url=git@github.com:_USER_/test-git-artifact.git --path test-git-artifact && cd test-git-artifact
+
+# 4. Add an artifact
+touch artifact-1.0
+git artifact add-n-push -t v1.0
+
+# 5. Find and retrieve the latest artifact
+git artifact find-latest
+git artifact fetch-co-latest
+```
 
 No external tools or complex configurations are needed. `git-artifact` leverages Git's powerful version control features to manage artifacts as if they were part of your source code.
 

From ed03a6b6556babd207f0fdff7870ee1e71f738ac Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 11:00:48 +0200
Subject: [PATCH 17/21] Revert changes to the set_opts_spec

---
 git-artifact | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/git-artifact b/git-artifact
index 5d9b1c7..ce8dee8 100755
--- a/git-artifact
+++ b/git-artifact
@@ -84,20 +84,20 @@ h,help          show the help
 q               quiet
 d               show debug messages
 
-options for 'init' and 'clone'
+ options for 'init' and 'clone'
 u,url=        the remote url
 p,path=       the optional path for init and clone 
 
-options for 'init', 'clone', 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
+ options for 'init', 'clone', 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
 b,branch=     use branch for local changes and pushes
 
-options for 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
+ options for 'add-n-tag', 'push', 'add-n-push', 'fetch-co'
 t,tag=         the tag to be created
 
-options for 'fetch-co-latest', 'find-latest'
+ options for 'fetch-co-latest', 'find-latest'
 r,regex=       the reg-ex pattern to latest of
 
-options for 'fetch-tags'
+ options for 'fetch-tags'
 s,sha1=       The sha1 of which to get tags from from 
 "
 }

From e5922847c64e7b269d77313b20b04ca94f15f272 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 11:20:03 +0200
Subject: [PATCH 18/21] Fix mermaid code block formatting in README

---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 240f89b..8363b9a 100644
--- a/README.md
+++ b/README.md
@@ -144,7 +144,7 @@ Git normally stacks the history; hence you cannot delete commits in the middle o
 
 The history of the git-artifact workflow can basically look like this:
 
-``` mermaid
+```mermaid
 %%{init: { 
     'gitGraph': {
         'loglevel' : 'debug',

From 917c9ff8a222f7aca8408b2ef29a515b6636b927 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 11:22:33 +0200
Subject: [PATCH 19/21] Move Key benefits to above quick start

---
 README.md | 22 +++++++++++-----------
 1 file changed, 11 insertions(+), 11 deletions(-)

diff --git a/README.md b/README.md
index 8363b9a..fde5016 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,17 @@
 
 > Effortless artifact management using Git repositories
 
-## Quick Start (TL;DR)
+## Key Benefits
+
+- **Seamless integration:** Manage artifacts alongside your source code using familiar Git tools.
+- **Efficient storage:** Artifacts are stored as independent commits, so you fetch only what you need.
+- **Traceability & integrity:** Tags and Git’s checksums provide clear versioning and authenticity.
+- **Easy cleanup:** Remove intermediate artifacts by simply deleting their tags.
+- **Unified workflow:** Eliminate the need for separate artifact repositories or complex tools.
+
+Whether for embedded, enterprise, or CI/CD environments, `git-artifact` streamlines artifact management by making it a natural extension of your existing Git processes.
+
+## Quick Start
 
 ```bash
 # 1. Install git-artifact binary in your PATH
@@ -27,16 +37,6 @@ git artifact fetch-co-latest
 
 No external tools or complex configurations are needed. `git-artifact` leverages Git's powerful version control features to manage artifacts as if they were part of your source code.
 
-### Key Benefits
-
-- **Seamless integration:** Manage artifacts alongside your source code using familiar Git tools.
-- **Efficient storage:** Artifacts are stored as independent commits, so you fetch only what you need.
-- **Traceability & integrity:** Tags and Git’s checksums provide clear versioning and authenticity.
-- **Easy cleanup:** Remove intermediate artifacts by simply deleting their tags.
-- **Unified workflow:** Eliminate the need for separate artifact repositories or complex tools.
-
-Whether for embedded, enterprise, or CI/CD environments, `git-artifact` streamlines artifact management by making it a natural extension of your existing Git processes.
-
 ## How to use `git-artifact`
 
 ### Install git-artifact

From 0e9763a93d9293c6f3113556355972cd6a7f1664 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Tue, 29 Jul 2025 13:17:57 +0200
Subject: [PATCH 20/21] Use git clone in the README.md

---
 README.md | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index fde5016..9cef495 100644
--- a/README.md
+++ b/README.md
@@ -15,14 +15,19 @@ Whether for embedded, enterprise, or CI/CD environments, `git-artifact` streamli
 ## Quick Start
 
 ```bash
-# 1. Install git-artifact binary in your PATH
-curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact
-
-# 2. Create a new repository on GitHub (open this URL in your browser)
+# 1. Create a new repository on GitHub [Make sure to not initialize it with a README or .gitignore]
 open https://github.com/new?name=test-git-artifact
 
+# Waits until you are done
 echo "Press Enter after creating the repository..." && read
 
+# 2. Install git-artifact binary in your PATH
+git clone https://github.com/Praqma/git-artifact.git
+
+export PATH=$(pwd)/git-artifact:$PATH
+
+git artifact -h
+
 # 3. Initialize the repository locally (replace _USER_ with your GitHub username)
 git artifact init --url=git@github.com:_USER_/test-git-artifact.git --path test-git-artifact && cd test-git-artifact
 
@@ -46,7 +51,7 @@ To install `git-artifact`, simply download or clone this repository and ensure t
 Or quickly install `git-artifact` by running:
 
 ```bash
-mkdir -p ~/.local/bin && curl -o ~/.local/bin/git-artifact https://raw.githubusercontent.com/praqma/git-artifact/main/git-artifact && chmod +x ~/.local/bin/git-artifact
+mkdir -p ~/.local/bin && git clone https://github.com/Praqma/git-artifact.git ~/.local/git-artifact && ln -sf ~/.local/git-artifact/git-artifact ~/.local/bin/git-artifact && git artifact -h
 ```
 
 Make sure `~/.local/bin` is included in your `PATH` environment variable:

From 230d47818cb3c184e53c1e4bd45af8e390abe8f1 Mon Sep 17 00:00:00 2001
From: Ahmed Magdy <magdy_a@outlook.com>
Date: Fri, 1 Aug 2025 01:05:29 +0200
Subject: [PATCH 21/21] Help should be called only using (-h) for now (--help)
 will be supported later when we install man pages

---
 git-artifact | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/git-artifact b/git-artifact
index ce8dee8..9b36c28 100755
--- a/git-artifact
+++ b/git-artifact
@@ -80,7 +80,7 @@ fetch-co-latest Get latest tag form remote using grep reg-ex and reset hard to i
 fetch-tags      Fetch all tags that points to a sha1 or HEAD - Useful in relation to detached HEAD and submodules
 
 --
-h,help          show the help
+h          show the help
 q               quiet
 d               show debug messages