diff --git a/.gitignore b/.gitignore
index 27c3231..ca3d1d9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,5 +2,6 @@ zsh/extraconfig.zsh
 zsh/env.zsh
 bash/extraconfig.bash
 nushell/history.*
+nushell/config/extra.nu
 .data
 bin-extra
diff --git a/nushell/config.nu b/nushell/config.nu
index 876d797..aca39ae 100644
--- a/nushell/config.nu
+++ b/nushell/config.nu
@@ -8,5 +8,7 @@ source ~/.config/nushell/config/gclone.nu
 source ~/.config/nushell/config/pass.nu
 source ~/.config/nushell/config/docker.nu
 source ~/.config/nushell/config/xrandr.nu
+source ~/.config/nushell/config/extra.nu
+source ~/.config/nushell/config/extra.nu
 source ~/.config/nushell/config/tfetch.nu
 
diff --git a/nushell/config/aliases.nu b/nushell/config/aliases.nu
index 9b8e38a..89cc789 100644
--- a/nushell/config/aliases.nu
+++ b/nushell/config/aliases.nu
@@ -1,4 +1,4 @@
-# tildize
+# replace /home/$USER by ~
 def tildize [] {
     if ($in | path split | zip ($env.HOME | path split) | all { $in.0 == $in.1 }) {
         ($in | str replace $env.HOME "~")
@@ -12,7 +12,7 @@ def rm-ext [] {
     $in | path parse | udpate extension "" | get parent stem | str join "/"
 }
 
-# ls aliases
+# ls builtin
 alias _ls = ls
 
 def _ls_format_mode [mode: string] {
@@ -29,16 +29,19 @@ def _ls_format_mode [mode: string] {
     [$r1, $w1, $x1, $r2, $w2, $x2, $r3, $w3, $x3] | each { $in | str join } | str join
 }
 
+# quick and easy ls
 def l [dir?: string] {
     let output = _ls (if $dir == null { "" } else { $dir }) | sort-by type name -i
     if ($output | length) == 0 { "" | cat } else { $output | grid -c -s "  " | cat }
 }
 
+# quick and easy ls
 def ls [dir?: string] {
     let output = _ls (if $dir == null { "" } else { $dir }) | sort-by type name -i
     if ($output | length) == 0 { "" | cat } else { $output | grid -c -s "  " | cat }
 }
 
+# ls with hidden files
 def la [dir?: string] {
     _ls -al (if $dir == null { "" } else { $dir })
         | sort-by type name -i
@@ -46,6 +49,7 @@ def la [dir?: string] {
         | select mode name target user size modified
 }
 
+# ls with details
 def ll [dir?: string] {
     _ls -l (if $dir == null { "" } else { $dir })
         | each { $in | update mode (_ls_format_mode $in.mode) }
@@ -53,14 +57,16 @@ def ll [dir?: string] {
         | select mode name target user size modified
 }
 
-# cool du (don't display everything)
+# du builtin
 alias _du = du
+
+# non recursive du
 def du [...args] {
     let parsed_args = if ($args | is-empty) { ["*"] } else { $args }
     $parsed_args | each { _du -a $in | select path apparent physical } | flatten
 }
 
-# cool df
+# df
 def df [] {
     ^df -h
         | str replace "Sys. de fichiers" "@"
@@ -77,13 +83,29 @@ def to-md [] {
 }
 
 # Useful aliases
+
+# colored ip
 alias ip = ip -c
+
+# neovim
 alias v = nvim
+
+# quit
 alias :q = exit
+
+# evince in background
 alias pdf = pueue add evince
+
+# ripgrep
 alias rg = rg -uu
+
+# mkdir && cd
 def --env mkcd [dir: string] { mkdir $dir; cd $dir }
+
+# run command in background
 alias pa = pueue add --immediate
+
+# show background commands
 def pst [] {
     pueue status -j
         | from json
diff --git a/nushell/config/docker.nu b/nushell/config/docker.nu
index 45f5b59..9ac47d6 100644
--- a/nushell/config/docker.nu
+++ b/nushell/config/docker.nu
@@ -1,10 +1,24 @@
 # docker aliases
+
+# lazydocker
 alias ld = lazydocker
+
+# docker-compose
 alias dc = docker-compose
+
+# docker-compose build
 alias dcb = docker-compose build
+
+# docker-compose build and push
 def dcp [] { docker-compose build; docker-compose push }
+
+# docker-compose up with build and remove-orphans
 alias dcu = docker-compose up -d --build --remove-orphans
+
+# docker-compose down
 alias dcd = docker-compose down
+
+# docker-compose down and up
 def dcr [] { docker-compose down; docker-compose up -d --build --remove-orphans }
 
 # kubernetes aliases
@@ -18,6 +32,7 @@ def _kube_kubes [] {
     _ls ~/.kubes | where type == dir | get name | path basename
 }
 
+# easily switch kube config
 def --env kube [name?: string@_kube_kubes] {
     use assert
 
@@ -39,19 +54,22 @@ def --env kube [name?: string@_kube_kubes] {
     $env.KUBECONFIG = $kube_config
 }
 
+# k9s
 alias kns = k9s -n all
 
-# minikube: don't erase my kubeconfig
+# start minikube with test kube
 def "minikube start" [] {
     $env.KUBECONFIG = ([$env.HOME, '.kubes', 'test', 'config'] | path join)
     ^minikube start
 }
 
+# stop minikube with test kube
 def "minikube stop" [] {
     $env.KUBECONFIG = ([$env.HOME, '.kubes', 'test', 'config'] | path join)
     ^minikube stop
 }
 
+# delete minikube with test kube
 def "minikube delete" [] {
     $env.KUBECONFIG = ([$env.HOME, '.kubes', 'test', 'config'] | path join)
     ^minikube delete
diff --git a/nushell/config/extra.nu b/nushell/config/extra.nu
new file mode 100644
index 0000000..225ac76
--- /dev/null
+++ b/nushell/config/extra.nu
@@ -0,0 +1 @@
+# Add non versionned custom aliases
diff --git a/nushell/config/gclone.nu b/nushell/config/gclone.nu
index ed3c609..0371e24 100644
--- a/nushell/config/gclone.nu
+++ b/nushell/config/gclone.nu
@@ -9,6 +9,7 @@ def _gclone_dirs [] {
         | uniq
 }
 
+# cd to a git directory
 def --env cdg [key: string@_gclone_dirs] {
     let dir = _ls ($env.GCLONE_PATH + "/*")
         | append (_ls ($env.GCLONE_PATH + "/*/*"))
@@ -70,6 +71,7 @@ def --env cdg [key: string@_gclone_dirs] {
     }
 }
 
+# clone repository in the right place
 def gclone [repo_url: string] {
 
     let attr = if ($repo_url | str starts-with "https://") {
diff --git a/nushell/config/git.nu b/nushell/config/git.nu
index 3d56905..ace1a95 100644
--- a/nushell/config/git.nu
+++ b/nushell/config/git.nu
@@ -1,16 +1,46 @@
 # git aliases
+
+# git
 alias g = git
+
+# git add
 alias ga = git add
+
+# git add --all
 alias gaa = git add --all
+
+# git checkout
 alias gco = git checkout
+
+# git checkout -b
 alias gcb = git checkout -b
+
+# git commit
 alias gc = git commit --verbose
+
+# git commit --all
 alias gca = git commit --verbose --all
+
+# git diff
 alias gd = git diff
+
+# git log
 alias glog = git log --oneline --decorate --graph
+
+# git pull
 alias gl = git pull
+
+# git push
 alias gp = git push
+
+# git status
 alias gst = git status
+
+# git status
 alias gs = git status
+
+# git merge
 alias gm = git merge
+
+# git push --set-upstream ...
 def gpsup [] { git push --set-upstream origin (git rev-parse --abbrev-ref HEAD) }
diff --git a/nushell/config/pass.nu b/nushell/config/pass.nu
index e03c718..09e4354 100644
--- a/nushell/config/pass.nu
+++ b/nushell/config/pass.nu
@@ -1,4 +1,5 @@
 # pass aliases / completion
+
 def _pass_completion [] {
     _ls ~/.password-store/**/* | each { |x|
         if $x.type == "file" {
@@ -20,8 +21,17 @@ def _pass_completion [] {
 
 export extern "pass" [ host?: string@_pass_completion ]
 
-def p [ arg: string@_pass_completion ] { pass $arg }
+# pass shortcut
+def p [ ...arg: string@_pass_completion ] {
+    for a in $arg {
+        pass $a
+    }
+}
+
+# pass with copy
 def pc [ arg: string@_pass_completion ] { pass --clip $arg }
+
+# open pdf encrypted file
 def ppdf [p: string] {
     pc thomas/key/pdf
     pueue add evince $p
diff --git a/nushell/config/update.nu b/nushell/config/update.nu
index 199e145..0aa62d6 100644
--- a/nushell/config/update.nu
+++ b/nushell/config/update.nu
@@ -15,6 +15,7 @@ def _update_args [] {
     ]
 }
 
+# update system
 def u [arg?: string@_update_args] {
     if $arg == null {
         ^update
diff --git a/nushell/config/xrandr.nu b/nushell/config/xrandr.nu
index 6bd3da9..5a3d8fd 100644
--- a/nushell/config/xrandr.nu
+++ b/nushell/config/xrandr.nu
@@ -1,4 +1,4 @@
-# nushell-ify xrandr
+# xrandr wrapper for nushell
 def xrandr [] {
     mut output = []
     mut current_screen: record<name: string, connected: bool, resolutions: list<string>> = {