Docker Dev is preconfigured with ZSH and a theme allowing to instantly recognise that a terminal session is running inside the container.
Run a single Docker container that stays active, and drop into it whenever you need to work on a Node project. This \"system-wide\" container:
\nNPM supply chain attacks are increasingly common. Recently, the multiple Shai-Hulud campaigns compromised many packages including some belonging to CrowdStrike, Zapier, PostHog, Postman, and many others.
Node.js hasn't been built with security in mind: any script, any dependency, has full access to the user's environment (file system, network, etc. which easily leads to credentials theft). Node's author himself recognised this and created Deno and its system of permissions for this reason.
A way to make working with Node more secure is to use a dev container: a Docker container inside which we run all our NPM commands and Node scripts. This isolates them from our host machine and drastically limits the damage in case of compromise.
However, with many projects, creating one dev container for each can quickly become cumbersome.
The solution presented here is to create a single, persistent, \"system-wide\" development container, inside which we will open all our projects.
Working inside a dev container doesn't create any overhead on Linux, as Docker works natively there. If you use another system, your experience might be different.
The full implementation is called Docker Dev and is available at github.com/zwyx/docker-dev.
\nFirst, you'll need to set up Docker if you don't have it already.
\nThen, clone the Docker Dev repository:
\ngit clone https://github.com/zwyx/docker-dev.git
cd docker-dev
Open the file docker-compose.yml, and modify the following line:
- ~/dev:/home/${USER}/dev
to replace dev with the name of your main workspace folder (containing all your repositories). The goal is for all your projects to have the same path on your host machine and inside the container. This will make switching from any directory on your host to the same directory inside the container very easy.
Do the same in the Dockerfile:
WORKDIR /home/${USERNAME}/dev
If you're on a Mac, also replace /home with /Users everywhere in these two files.
Now, start the container:
\ndocker-compose up -d
This container is quite tied to my personal configuration and preferences. If something doesn't work, open Dockerfile and docker-compose.yml to make any necessary adjustments.
On your host machine, add this alias to your ~/.zshrc (or equivalent):
alias d='docker exec -it -w \"$PWD\" dev zsh'
Now, if you have correctly configured your workspace folder during the previous step, you can navigate to any project or subdirectory inside it, and simply run:
\nd
to open a terminal session inside the dev container, at the same location:
\nInstall the official Dev Containers extension.
\nThen in VS Code, open the command palette, run Dev Containers: Attach to Running Container... and select the container dev.
Now open a project's folder in this window, and that's it: you can start working with the same dev environment you're used to.
\nSome VS Code extensions, like Prettier and ESLint, need to run inside the container. Simply open the Extensions view in your sidebar and click Install in container on the extensions you wish to use.
\nHaving extensions running inside the container is a great security improvement because VS Code extensions, like NPM packages, have full access to your system and can be compromised. Even worse: VS Code, by default, auto-updates them! Which means, if an extension gets compromised, it could land on your machine without you doing anything.
So having extensions running inside the container is much safer: compromised extensions won't have access to your host system.
However: not all extensions run inside the container. Some extensions, like themes, always run on the UI on your host machine, so they do have access to your system. I highly recommend to disable auto-update for these extensions, and to update them manually when nothing is going on in the news.
You can have as many projects as you want opened simultaneously, each on its own VS Code window attached to the container.
\nHowever, if a VS Code window is already attached to the container, then running again the command Dev Containers: Attach to Running Container... will simply focus the existing window, which can be confusing.
\nTo make things simpler, set the VS Code setting window.openFoldersInNewWindow to on.
Now, in a window that is already attached to the container, run the command File: Open Folder..., select the folder of another project you'd like to open, and press Enter. A new window – also attached to the container – will open with this project.
\nSet a keyboard shortcut for this command, for convenience. (I set Ctrl+O, as I only use Ctrl+P to open files.)
You can decorate windows that are attached to the container differently than regular windows, to quickly distinguish them.
\nFor instance, you can make the window's title start with a package 📦 icon, and colour its title bar:
\n![\"Two](\"https://zwyx.dev/assets/images/vscodeWindowCustomisation-d44399addd12664cc250f8f1b1ea5715.webp\")
docker-dev is a regular window, zwyx.dev is attached to the containerOpen VS Code's settings and select the Remote tab. Settings in this tab apply only to windows that are attached to the container:
\nThese settings are saved in ~/.vscode-server/data/Machine/settings.json in the container's file system. Docker Dev includes an example copy of this file, which is copied to the correct location during the container's creation (see the Dockerfile).
Now that you have your container, you'll want to run everything Node-related inside it (npm i, npm run dev, etc.).
To run web applications, you'll need to expose their ports to be able to access them from your browser on your host machine.
\nWe could configure the ports in the docker-compose.yml file, but exposing ports this way can only be done before the container starts. It cannot be changed while it is running.
A more practical solution is to use VS Code to forward our ports. Contrary to Docker, VS Code can start and stop forwarding ports while the container is running.
\nOpen the command palette and run Forward a port, enter the port number, and press Enter. For example, I am forwarding port 3000 to run Docusaurus as I'm writing this blog post, to preview it in my browser.
Note that some dev servers require an additional argument for container networking, usually --host 0.0.0.0. Docker Dev is configured with a few useful aliases, such as:
alias nrd='npm run dev -- --host 0.0.0.0'
On your host machine, deleting a file from VS Code's File Explorer usually sends this file to your system's trash.
\nInside a container however, VS Code isn't able to do this by default, and deletes files permanently instead.
\nIf you want to have the trash functionality inside your container, install the Remote Trash extension. (Docker Dev is already configured with trash-cli, which is required for this extension to work.)
Docker Dev comes preconfigured with NVM to manage your Node versions. To avoid taking up extra space unnecessarily, it uses the downloaded Node versions already present on your host machine. (See in docker-compose.yml, the line - ~/.nvm:/home/${USER}/.nvm that mounts your host's ~/.nvm folder inside the container.)
Docker Dev provides useful scripts to integrate it with other applications (Git clients, etc.).
\nUse the script docker-dev/misc/open-in-vscode.sh to configure the external editor of any application that supports it. For instance with Sublime Merge:
![\"Sublime](\"https://zwyx.dev/assets/images/sublimeMerge-4e4367d9755e0eef123cbd2f5163a0ae.webp\")
open-in-vscode.sh resolves the closest Git repository from the path passed as argument (or the current working directory if no argument is provided), and opens it in either a VS Code window attached to the dev container, or a regular one if the directory contains a file named .nocontainer. (If a window on this project is already open, VS Code will simply focus it.)
Another script – docker-dev/misc/open-in-terminal.sh – opens the path passed as argument in either a terminal session inside the dev container, or a regular one if the directory contains a file named .nocontainer.
If you need to create .nocontainer files, but you'd prefer not to commit them or add them to every project's .gitignore, you can simply add .nocontainer to your global ignore file:
.nocontainer
The scripts in the previous section allow you to open VS Code inside the dev container from another application. But how to do the opposite: open an external application from inside the dev container?
\nThe Host command execution feature of Docker Dev addresses exactly this: it allows to execute commands on the host machine from within the container.
\nIt uses a messaging system with a service that watches for command requests from the container and executes them on the host.
\ninotify-tools:sudo apt install inotify-tools
chmod +x host-exec-service/host-exec.sh
<path-to-docker-dev> below:mkdir -p ~/.config/systemd/user
ln -s \"<path-to-docker-dev>/host-exec-service/host-exec.service\" ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable host-exec.service
systemctl --user start host-exec.service
~/.docker-dev to be mounted:docker-compose up --build -d
Create host-exec-xxx files specific to your use case (like the ones in docker-dev/container-content) and adapt the file docker-dev/host-exec-service/host-exec.sh (mainly the array ALLOWED_COMMANDS – restart the service after modifying this file: systemctl --user restart host-exec.service).
For instance, the file host-exec-sublime-merge allows to open Sublime Merge from a VS Code window attached to the container. It uses the extension History in Sublime Merge, with its setting history-in-sublime-merge.path in the container set to host-exec-sublime-merge. It also requires a script open-in-sublime-merge.sh (see host-exec.sh).
Make sure the host command execution service maintains the following features in order to prevent malicious scripts from escaping the container:
\nSetting up this system takes 20-30 minutes. In exchange, you get:
\n.nocontainer file.For anyone who frequently works with Node.js projects, especially those involving third-party packages or untrusted code, this setup provides a significant security improvement with minimal overhead.
\nGive it a try at github.com/zwyx/docker-dev.
", "url": "https://zwyx.dev/blog/docker-dev", "title": "Protect yourself from malicious NPM packages with a system-wide dev container", "summary": "Isolate Node.js development from your host system using a persistent Docker container.", "date_modified": "2025-11-27T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "docker", "security", "npm", "node", "vscode" ] }, { "id": "https://zwyx.dev/blog/base-conversions-with-big-numbers-in-javascript", "content_html": "For the Library of Babel, I needed to convert very big numbers — hundreds of thousands of digits — from a base to another.
\n\nHowever, BigInt is limited:
BigInt() accepts strings in bases 2, 8, 10, and 16, only;toString() accepts a base of between 2 and 36.I needed to work with bases 29 and 94, BigInt wasn't able to handle this. So I tried to implement the necessary algorithms in JavaScript.
To convert a string to an integer, the classic algorithm is:
\nconst fromBase = (text: string, alphabet: string = \"0123456789\"): bigint => {
\tconst base = BigInt(alphabet.length);
\tlet result = 0n;
\t// Start from the left of the string
\tfor (let i = 0; i < text.length; i++) {
\t\t// for each digit, take the previous result,
\t\t// multiply it by the base, and add the new digit
\t\tresult = result * base + BigInt(alphabet.indexOf(text.charAt(i)));
\t}
\t/* or we could do that, but it's slower:
\t// starting from the right of the string
\tfor (let i = text.length - 1; i >= 0; i--) {
\t\t// multiply each digit by the base to the power of
\t\t// the digit position, and add it to the result
\t\tresult +=
\t\t\tBigInt(alphabet.indexOf(text.charAt(i))) *
\t\t\tbase ** BigInt(text.length - 1 - i);
\t}
\t*/
\treturn result;
};
However, this is quite slow: it takes 30s on my machine to convert a string containing 500,000 random digits in base 10. (I tried to compile it to WebAssembly with AssemblyScript, but it made it even slower.)
\nWhereas it takes V8's BigInt only 100ms!
Turns out, BigInt uses a different algorithm, which can be found in V8's FromStringLarge function.
I'll leave it to you to read the description in V8's source code to understand how it works, and here is my JavaScript version:
\nconst fromBase = (text: string, alphabet: string = \"0123456789\"): bigint => {
\tconst base = BigInt(alphabet.length);
\tlet parts = text
\t\t.split(\"\")
\t\t.map((part) => [BigInt(alphabet.indexOf(part)), base]);
\tif (parts.length === 1) {
\t\treturn parts[0][0];
\t}
\tlet pairFull: boolean;
\twhile (parts.length > 2) {
\t\tpairFull = false;
\t\tparts = parts.reduce<bigint[][]>((acc, cur, i) => {
\t\t\tif (!pairFull) {
\t\t\t\tif (i === parts.length - 1) {
\t\t\t\t\tacc.push(cur);
\t\t\t\t} else {
\t\t\t\t\tacc.push([
\t\t\t\t\t\tcur[0] * parts[i + 1][1] + parts[i + 1][0],
\t\t\t\t\t\tcur[1] * parts[i + 1][1],
\t\t\t\t\t]);
\t\t\t\t\tpairFull = true;
\t\t\t\t}
\t\t\t} else {
\t\t\t\tpairFull = false;
\t\t\t}
\t\t\treturn acc;
\t\t}, []);
\t}
\treturn parts[0][0] * parts[1][1] + parts[1][0];
};
It now takes 120ms to do the conversion! Just slightly slower than native BigInt. (And without any optimisations that are mentioned in V8's code.)
It's a bit counter intuitive, because this algorithm does about 1,000,000 iterations, instead of 500,000 for the classic algorithm (which does one for each digit). The reason is apparently that the multiplications are smaller, and possibly more optimisable because involving parts of the same size.
\nTo convert an integer to a string, the classic algorithm is the successive division method:
\nconst toBase = (value: bigint, alphabet: string = \"0123456789\"): string => {
\tconst base = BigInt(alphabet.length);
\tlet result = \"\";
\t// At start, the dividend is equal to the value
\tlet dividend = value;
\tlet remainder;
\twhile (dividend >= base) {
\t\t// We get the remainder of the dividend modulo the base
\t\tremainder = dividend % base;
\t\t// and we append it to the result, from right to left
\t\tresult = alphabet[Number(remainder)] + result;
\t\t// then we divide the dividend by the base
\t\t// and that gives us the dividend for the next iteration
\t\tdividend = dividend / base;
\t}
\tresult = alphabet[Number(dividend)] + result;
\treturn result;
};
However, this is again quite slow: 30s to convert a bigint of 500,000 random digits in base 10.
\nFor this too, V8's BigInt is much faster, and uses a different algorithm, divide-and-conquer conversion.
I recommend again to read the description in V8's code, as I couldn't explain it better, and here is my JavaScript version:
\nconst toBase = (value: bigint, alphabet: string = \"0123456789\"): string => {
\tconst base = BigInt(alphabet.length);
\tlet result = \"\";
\tconst divisors = [base];
\tconst numberOfBitsInValue = value.toString(2).length;
\twhile (divisors.at(-1).toString(2).length * 2 - 1 <= numberOfBitsInValue) {
\t\tdivisors.push(divisors.at(-1) ** 2n);
\t}
\tconst divide = (dividend: bigint, divisorIndex: number) => {
\t\tconst divisor = divisors[divisorIndex];
\t\tconst remainder = dividend % divisor;
\t\tconst newDividend = dividend / divisor;
\t\tif (divisorIndex > 0) {
\t\t\tdivide(remainder, divisorIndex - 1);
\t\t\tdivide(newDividend, divisorIndex - 1);
\t\t} else {
\t\t\tresult = `${alphabet[Number(newDividend)]}${
\t\t\t\talphabet[Number(remainder)]
\t\t\t}${result}`;
\t\t}
\t};
\tdivide(value, divisors.length - 1, true);
\tresult = result.replace(new RegExp(`^${alphabet[0]}*`), \"\");
\treturn result;
};
It now takes 150ms to do the conversion! (Also without any optimisations.)
\nAnd that's it. These two fast algorithms made possible my version of the the Library of Babel, which works entirely client-side.
\nThanks to these algorithms, I was able to finish the the Library of Babel. Every operation was taking a couple of seconds, at most, on my computer.
\nHowever, when testing the app on my phone, I realised that one operation was very slow: it took more than 3 minutes!
\nIt turned out that it was a .toString() call on a very large bigint. The need was to convert this bigint to a string in base 10, so I didn't bother changing this .toString() to use the new algorithm toBase, because .toString() is able to handle base 10.
However, V8's source code shows that the fast .toString algorithm is behind the flag V8_ADVANCED_BIGINT_ALGORITHMS.
I guess this flag is ON when Chrome is built for Linux desktop, but OFF when it's built for Android.
\nI simply replaced .toString() by a call to toBase(...) and the app became fast on my phone too!
There is also a call to .toString(16) on the same number, but this one is very quick. The algorithm for base 16 must be much faster because it just has to split every byte into two hexadecimal values. So I didn't have to change this one.
There is a TC39 proposal to give BigInt more capabilities, but as of 2023, it doesn't look like it's getting much traction.
Use TypeScript to ensure the validity of your i18next translations.
\n\nA demo project is available at github.com/zwyx/typesafe-translations
Translating software with i18next is easy:
\nHello, by a function call with a key, t(\"hello\"),{
\t\"hello\": \"Hello\"
}
{
\t\"hello\": \"Bonjour\"
}
The problem is that there is no easy way of detecting issues in translations. For instance, if we change the key from hello to hi, then we have to update all the translation files manually.
Many utilities have been made to improve the situation, often requirering extra build steps. Recently however, it has became very nice and easy with i18next and TypeScript.
\nThis example uses a classic React single-page application, with no Server-Side Rendering or Static Site Generation. If you plan to use SSR or SSG — for instance with Next.js — you will have a more complex setup to create, in order to prevent hydration errors.
The types will be set by the translation file of our main language. For us, it will be English. It will become the source of truth.
\nAll other language files, as well as the code of the app, will be type checked against it.
\nWe start by creating the English translation file, as a TypeScript file:
\nexport const en = {
\tapp: {
\t\thello: \"Hello\",
\t},
};
Then, we want to create a type derived from this file, that we'll use with the other languages.
\nTo do this, we create a DeepReplace utility type. It creates an interface from an object, containing all the keys of this object, with all their types changed to string.
// https://stackoverflow.com/questions/60437172/typescript-deep-replace-multiple-types
type Replacement<M extends [unknown, unknown], T> = M extends unknown
\t? [T] extends [M[0]]
\t\t? M[1]
\t\t: never
\t: never;
export type DeepReplace<T, M extends [unknown, unknown]> = {
\t[P in keyof T]: T[P] extends M[0]
\t\t? Replacement<M, T[P]>
\t\t: T[P] extends object
\t\t ? DeepReplace<T[P], M>
\t\t : T[P];
};
To create our I18nLocale type, we use DeepReplace with the en object. The English translation file becomes:
import { DeepReplace } from \"~/lib/utils\";
export const en = {
\tapp: {
\t\thello: \"Hello\",
\t},
};
export type I18nLocale = DeepReplace<typeof en, [string, string]>;
We want to use our I18nLocale in all other translation files:
import { I18nLocale } from \"./en\";
export const fr: I18nLocale = {
\tapp: {
\t\thello: \"Bonjour\",
\t},
};
Our translation files are now typed. A typo, or a missing key, is detected immediately:
\nWe also now have intellisense available in the translation files:
\nIn order to let i18next know about our types, we first create a resources constant containing all our languages, in the i18next initialisation file:
import { en } from \"./locales/en\";
import { fr } from \"./locales/fr\";
export const resources = {
\ten,
\tfr,
};
We then create the file src/@types/i18next.d.ts – the path is important – containing:
import { resources } from \"@/i18n/i18n\";
declare module \"i18next\" {
\tinterface CustomTypeOptions {
\t\tresources: (typeof resources)[\"en\"];
\t}
}
And that's it! Now our types are checked in the code:
\nAnd we have Intellisense:
\n![\"Intellisense](\"https://zwyx.dev/assets/images/5-b6971f94911e1d8a1ce2223070007c2b.jpg\")
For more details on the implementation, check out the demo project at github.com/zwyx/typesafe-translations.
", "url": "https://zwyx.dev/blog/typesafe-translations", "title": "Type-safe translations with TypeScript and i18next", "summary": "Use TypeScript to ensure the validity of your i18next translations.", "date_modified": "2023-09-19T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "i18n", "i18next", "vite", "typescript", "react", "tailwind", "shadcnui" ] }, { "id": "https://zwyx.dev/blog/proper-dark-theme", "content_html": "Three states, no flash, reactive. Test it at zwyx.github.io/proper-dark-theme
\n\nAlthough implementing dark theme manually might sound like reinventing the wheel, it's actually easy and there are good reasons to do it:
\nThe user must be able to choose same as device (which should be the default), light, or dark.
If the current theme is dark, the page must not display a white background while it loads (very annoying at night, and possibly problematic for users with vision disabilities).
\nChanging the theme — including the device's theme, when same as device is selected — should be instantly effective on the page, without requiring to refresh it.
In order to have these features, and not being dependent on a specific stack, I found that the best it to implement dark theme manually.
Once we know how to do it, we can reuse it everywhere. Instead of installing it as a library, we copy and paste it. We « own the code », which is a philosophy I first discovered with Shadcn UI.
Our way of doing it will be:
\nlight or dark to the root HTML element, andCSS variables make it easy to have our app reactive: changing the class on the root HTML element instantly change all the color in the website, no refresh necessary.
\n:root {
\t/* variables for light theme */
\t--background: 0 0% 100%;
\t--foreground: 222.2 84% 4.9%;
}
:root.dark {
\t/* variables for dark theme */
\t--background: 222.2 84% 4.9%;
\t--foreground: 210 40% 98%;
}
To prevent the flash, we want to apply the light or dark class as soon as possible. This is what this small block of JavaScript, to be placed in the head of our HTML, does:
<meta name=\"theme-color\" content=\"#020817\" />
<script>
\t// Set the theme's class as soon as possible to prevent a flash of the wrong theme
\tvar lightThemeName = \"light\";
\tvar darkThemeName = \"dark\";
\tvar storedTheme = localStorage.getItem(\"theme\");
\tvar theme;
\tif (storedTheme === lightThemeName || storedTheme === darkThemeName) {
\t\ttheme = storedTheme;
\t} else if (matchMedia(\"(prefers-color-scheme: dark)\").matches) {
\t\ttheme = darkThemeName;
\t} else {
\t\ttheme = lightThemeName;
\t}
\tdocument.documentElement.classList.add(theme);
\tif (theme === lightThemeName) {
\t\tdocument
\t\t\t.querySelector('meta[name=\"theme-color\"]')
\t\t\t?.setAttribute(\"content\", \"#ffffff\");
\t}
</script>
The theme-color meta tag is optional, it's useful mainly if our app is a PWA. When using it, we want to keep it in sync with our theme color.
The JS has to maintain two state variables:
\nlight, dark, or same as deviceslight, when:\nlightsame as device and the device's theme is lightdark, when:\ndarksame as device and the device's theme is darkTo do that, the JS has to:
\nmatchMedia(\"(prefers-color-scheme: dark)\")
\t.addEventListener(\"change\", ()=>{ ... });
I won't include the rest of the code here, instead I invite you to have a look at the implementation made with TypeScript and React for the demo project.
\nI consider this three-state implementation to be the best at the moment, but I hope that it won't be necessary in the future.
\nWhen all operating systems and all web browsers will implement dark theme seamlessly, then offering to the user the possibility to change the theme for a particular website might start to be seen as unnecessary. At least, the setting could be buried in a dialog box instead of being directly available on the top right of the page.
\nHere's another way of defining the CSS variables, which greatly reduces the amount of JS required. We use a media query to apply the dark theme when it's the system preference and the user hasn't selected the light theme.
\n:root {
\t/* variables for light theme */
\t--background: 0 0% 100%;
\t--foreground: 222.2 84% 4.9%;
}
:root.dark {
\t/* variables for dark theme */
\t--background: 222.2 84% 4.9%;
\t--foreground: 210 40% 98%;
}
@media only screen and (prefers-color-scheme: dark) {
\t:root:not(.light) {
\t\t/* variables for dark theme */
\t\t--background: 222.2 84% 4.9%;
\t\t--foreground: 210 40% 98%;
\t}
}
By doing that, the JS doesn't have to listen for changes of the system's theme anymore.
\nThis is how I used to do it. However, it has a few drawbacks:
\nsame as device (Tailwind's dark: selector, for instance, doesn't work).![\"Gears\"](\"https://zwyx.dev/assets/images/gears-unsplash-xRDuEeG1TVI-845693b4f819dad5a2b8c416aef8f540.webp\")
Track changes in your config files using a Git repository.
\n\nDotfiles is the name given to the tiny text files containing the configuration for a piece of software. They're often placed in the your home directory and start with a dot to be hidable. We'll not limit ourselves to strictly dotfiles in this article though, what we'll do apply to any configuration file.
\nBacking up these files and track changes to them is a good idea. It will be useful if you have to reinstall your system or set up a new machine, and, probably more often, you can restore your configuration if the corresponding software blows a gasket. It can happened with VS Code and its feature \"Settings Sync\" for instance: I was using VS Code on my machine and on GitHub.dev, and settings got messed up. Thanks to the fact that my VS Code's config is tracked in Git, I just had to discard the current changes to have my config back.
\nGit is the first choice to track changes in text files. However, all these config are in different places on the file system.
\nSo how to gather them in one Git repository? There are a few methods:
\nThis method is a pain: creating all the links is cumbersome. Also, some software delete and recreate their configuration files instead of modifying them, which breaks the links without us noticing it.
\nThis isn't recommended if you have other Git repositories anywhere in your home directory, as there would be a risk of interference.
\nThe idea is to create a bare repository — which is simply a Git repository without a work tree — and then set its worktree to your home directory.
\n\n\nHow is this different from method 2?
\nNothing shows that the home folder is the root of a repo.
\ngit, run in your home folder, will not see it as a repository, so has no risk of interfering with other repos present in your home folder.
\n\nIf we set the worktree of the bare repository... then it's not bare anymore!
\nIndeed. This method is known as the \"bare repo method\", but it might just be in order to avoid confusion with method 2. We actually don't need a bare repo, we just need to change the location of a repo's worktree. Don't be confused by this, or worried that it's too complex.
\n
This article is about setting up this method.
\nPlease read carefully and only execute commands that you fully understand. Wrong Git commands executed anywhere in your home directory could lead to a loss of data.
Start by creating a bare repository:
\ngit init --bare ~/my-config
The folder ~/my-config now contains the config repository. Now we want to set its worktree to be the home directory (replace <your-name> in the block below):
cd ~/my-config
git config --unset core.bare
git config core.worktree '/home/<your-name>'
git config status.showUntrackedFiles no
The file ~/my-config/config should look like this:
[core]
\trepositoryformatversion = 0
\tfilemode = true
\tworktree = /home/<your-name>
[status]
\tshowUntrackedFiles = no
Let's add two functions in your .zshrc (or equivalent) to easily add and untrack config files:
# We use functions instead of aliases to have folder and file name completion
config-add() {
\tgit --git-dir=\"$HOME/repo/config/.git-bare\" add -f $@
}
config-untrack() {
\tgit --git-dir=\"$HOME/repo/config/.git-bare\" rm --cached $@
}
config-add .zshrc
config-untrack .zshrc
Execute regular git commands in your config repository — git add, git commit, git push, etc. HOWEVER, be very careful: commands like git clean could delete every untracked files from the home directory!
That's it. Your config files are tracked in a git repo. Keep reading for a few more tips.
\nYou can create a cron job that commits and pushes your config once a week:
\ncd \"$HOME/my-config\"
git add -A
git commit -a -m \"Weekly commit\"
git push
crontab -e
30 12 * * 5 <path-to-script>
You can also add other useful tasks in the script, just before the the three git commands. For instance:
code --list-extensions > ~/.config/vscode-extensions.txtdconf dump / > ~/.config/dconf.inicrontab -l > ~/.config/crontab.txtAdding files that are already present in another Git repository seems to be impossible.
\nFor instance, I didn't find a way to add ~/.nvm/default-packages, because ~/.nvm is a Git repository.
So for this kind of file, I use the hard link method:
\nln `~/.nvm/default-packages` `~/my-config/default-packages`
At the moment, Sublime Merge ignores the property status.showUntrackedFiles and will show all the untracked files of the home folder.
To prevent this, it is possible to add a .gitignore in the repo's root folder. This .gitignore mainly needs to contain a *, to hide all untracked files, although you can also \"unhide\" specific subfolders if you want your weekly commit to automatically includes new files from these folders.
Here's an example:
\n/*
!.gitignore
!.config/Code
.config/Code/*
!.config/Code/User
.config/Code/User/*
!.config/Code/User/snippets
.gitignore;.config/Code....config/Code/User....config/Code/User/snippets, so all files in this folder will be tracked in our config.This .gitignore file has a side effect on git checkout. Indeed, usually, when cloning a repository and running git checkout, if some files in the worktree are different than the ones in the repository, git displays the message error: The following untracked working tree files would be overwritten by checkout: .... But with this .gitignore in the home directory, git checkout will simply override the files that are in the home directory by the ones from the repository. Without warning!
However, the point it to be able to use Sublime Merge, so we don't need git checkout. We simply open the repository in Sublime Merge, keep the files we want, and we discard the others.
Sublime Merge has another bug when working with a repository whose work tree isn't next to the repo itself: the corresponding tab isn't reopen correctly. So, here's an alias to quickly open your config repo in Sublime Merge:
\nalias config-open-in-sublime-merge='\"$HOME/.config/open-in-sublime-merge.sh\" \"$HOME/my-config\"'
#!/bin/bash
if pgrep sublime_merge; then
\tif [[ -d $1 ]]; then
\t\t/opt/sublime_merge/sublime_merge \"$1\"
\telse
\t\t/opt/sublime_merge/sublime_merge \"$(dirname \"$1\")\"
\tfi
else
\txmessage \"Start Sublime Merge before to prevent losing all open tabs.\"
fi
As you can see, we check that sublime_merge is already running before attempting to open the repository. This is because of yet another bug in Sublime Merge (at this point you might be wondering why I use this tool... I swear it's a great tool, altough it's definitely frustrating to be paying for a licence and barely receive any reply to the bug reports I create).
![\"GitHub](\"https://zwyx.dev/assets/images/skyline-zwyx-2021-119aa1652e7ad3f01853ad0715589ac8.webp\")
Combine your contributions from any repository on your GitHub contribution graph.
\n\nA friend and I used to work at the same company, where we were using GitHub.
\nEvery year, our contribution graphs looked nice and it was kinda rewarding.
\n![\"A](\"https://zwyx.dev/assets/images/contribution-graph-rotated--5deg-a71e5daa065d8a87b758615f58415fb6.webp\")
You can do more than just look at it on your GitHub profile page: GitHub Skyline lets you generate a 3D version of it — which is the image at the top of this article. You can then download the 3D file and print it:
\n![\"Code](\"https://zwyx.dev/assets/images/skyline-zwyx-2021-printed-858309e6327f06a95044176afbfada1f.webp\")
The companies we work for now however, use other Git hosting providers. Which means... no more contribution graphs on GitHub 😢
\nThis is where Tim had a beautiful idea: create a tool that regularly scans our work repositories, and creates empty commits in a repository hosted on GitHub! Each empty commit corresponds to a commit made by ourselves in our work repositories, and is made with the same commit date.
\nThe repository gathering all these empty commits can be private on GitHub. (Although even if it's public, no content is present in it.)
\nBrilliant!
\nThe tool is own-contribution-graph. To use it, simply:
\nnpm i -g own-contribution-graph
create the configuration file following the instructions in the ReadMe,
\nrun the following command:
\nowncontributiongraph --config=<path-to-the-json-config-file>
own-contribution-graph to the file ~/.nvm/default-packages, so nvm automatically installs it when I install a new version of Node.Our contributions graphs are alive again!
\nThere is a difference though: the merge method we used to use was rebase merging, where all commits from a feature branch are applied one by one on the main branch. Now we use squash merging, were all commits are squashed together into one commit that is applied on the main branch. So less contributions appear on the graph.
", "url": "https://zwyx.dev/blog/own-contribution-graph", "title": "Consolidate your contribution graph", "summary": "Combine your contributions from any repository on your GitHub contribution graph.", "date_modified": "2023-03-31T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "git" ] }, { "id": "https://zwyx.dev/blog/indentation-for-accessibility", "content_html": "It's quite obvious, for consistently looking code, spaces are best.
\nHowever, does one also has consistency among the people they work with?
\nIt might not be the case: some people might have impaired vision.
\nOn an open source project, one might not even know how \"consistent\" are the people working with them.
\n\nSome require such big font sizes, that being able to set the tab width to 1 is a big deal. (I am short-sighted, and although I don't have special needs other than wearing glasses, I can understand how useful it can be for others).
\nAfter working years on projects using spaces, and years on projects using tabs, what's apparent to me is that for most developers, tabs or spaces don't change anything. We adapt easily to one choice or the other.
\nThe only persons for whom it matters, are people with special needs. And for them, tabs are better. Shouldn't this be a done deal?
\nThis is even more true these days, as many languages now have great tools to autoformat our code. If an autoformatter is available for a language, then using it should be a priority. It is SO great to not have ever to think about indentation or formatting.
\nWith tabs, the code will not consistently look the same on everyone's screen anymore, but another thing will become consistent: a good experience for everyone.
\nThis is for this exact reason that the web has introduced media queries like prefers-color-scheme and prefers-contrast. We want to improve accessibility of websites; source codes deserve the same.
So, my recommendations is to set the project settings to fix the differences between operating systems that developers shouldn't have to deal with, and set some preferences like trimming trailing whitespaces.
\nThat's it. Do not set the tab width, it is a user setting.
\nForcing the tab width would be like forcing a bright high contrast theme for everyone in the project.
\nSo for example, here's an .editorconfig file:
# https://editorconfig.org
[*]
charset = utf-8
end_of_line = lf
indent_style = \"tab\"
trim_trailing_whitespace = true
insert_final_newline = true
And a .vscode/settings.json file:
{
\t\"files.encoding\": \"utf8\",
\t\"files.eol\": \"\\n\",
\t\"files.trimTrailingWhitespace\": true,
\t\"files.insertFinalNewline\": true,
\t\"files.trimFinalNewlines\": true,
\t\"editor.insertSpaces\": false,
\t\"editor.defaultFormatter\": \"esbenp.prettier-vscode\"
}
(We sometimes read that developers who use spaces make more money. Does it sound like BS? It probably is. Developers using spaces could simply be paid more because they're older (so have old habits). Young developers (paid less) could have answered that they use tabs because they press the Tab key when indenting. And there's more, see the comments below the original post.)
\nTL;DR: I recommend to use tabs and to not force their width (and to use an automatic formatter for everything else if possible). Of cours, this doesn't apply if the project/language you work with doesn't allow it for technical reasons.
\nThis post was originally my answer to this StackOverflow question.
", "url": "https://zwyx.dev/blog/indentation-for-accessibility", "title": "Indentation for accessibility", "summary": "The real reason to use tabs over spaces", "date_modified": "2023-01-05T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "code", "indentation", "formatter", "prettier" ] }, { "id": "https://zwyx.dev/blog/hello-docusaurus", "content_html": "I've investigated different static site generators — SSGs — in order to set up a proper blog for this website. I've read about a lot of them, tried a few. My favourite by far is Docusaurus, the one this site is now built with.
\n\nAs I'm working on complex web apps during the day, SSGs make evening projects feel like holiday.
\nStill, I found that many of them require quite some tinkering before achieving desired results. In theory, to have a quick website set up, we can start from a template. But unfortunately this is where most of the pain come from. Many templates I looked at where incomplete, old, unmaintained, or simply ugly.
\nDocusaurus is the one which has the best of both:
\nThere is only one at the moment. It has basically everything I wanted and it's very nice. So it's much better than a choice of 100 useless templates. It might be a bit of a problem for someone really not liking it... but still, wait for the next point.
\nDocusaurus provides multiple ways to customise the styling and layout, depending on what we want to change, and how deep we want to change it. From creating React components and use them in MDX, to the brilliant swizzling method allowing to easily cherry pick a component to wrap it or replace it (there is an example in the Add comment system section below).
\nI will write about the choices I've made during the building of this blog. I won't detail every steps — official docs are better sources and will stay up to date.
npx create-docusaurus@latest your-project-name classic --typescript
This is all what's needed to have a complete website with dummy pages ready to be filled with content.
\nIf you're sick of having a new browser tab being opened every time you run the start command, append --no-open.
Prettier formats Markdown well, it will be appreciated while writing blog posts.
\n/blogI wanted the blog to be the only content of the site for the moment. But I didn't want to make the blog base URL simply /, as all the post links would be in the format <domain>/<post>, which could potentially become annoying if I wanted to add other types of content to the site in the future.
So I kept the blog base URL /blog (post links are <domain>/blog/<post>), and I created a redirect from / to /blog.
Server-side redirects are best, but as I'm hosting the site on GitHub Pages, this isn't an option.
Docusaurus provides a plugin for client-side redirects:
\nnpm i @docusaurus/plugin-client-redirects
plugins: [
\t[
\t\t\"@docusaurus/plugin-client-redirects\",
\t\t/** @type {import('@docusaurus/plugin-client-redirects').Options} */
\t\t({
\t\t\tredirects: [
\t\t\t\t{
\t\t\t\t\tfrom: \"/\",
\t\t\t\t\tto: \"/blog\",
\t\t\t\t},
\t\t\t],
\t\t}),
\t],
],
docspresets: [
\t[
\t\t\"classic\",
\t\t...
\t\t\tdocs: false,
Adding the following makes links to the blog look pretty when shared.
\npresets: [
\t[
\t\t\"classic\",
\t\t...
\t\t\tblog: {
\t\t\t\tblogTitle: \"<Blog title>\",
\t\t\t\tblogDescription: \"<Blog description>\",
themeConfig:
\t...
\t\timage: \"<Image path>\",
Just because I want all the shiny new stuff, I activated all the types of feeds.
\npresets: [
\t[
\t\t\"classic\",
\t\t...
\t\t\tblog: {
\t\t\t\tfeedOptions: {
\t\t\t\t\ttype: \"all\",
\t\t\t\t\ttitle: \"<Blog title>\", // By default, it's in the format `<Site name> Blog`
\t\t\t\t\tdescription: \"<Blog description>\", // Same here
\t\t\t\t},
Giscus is a great comment system powered by GitHub Discussions.
\nInstall its React component:
\nnpm i @giscus/react
Use giscus.app to set up and retrieve your configuration for Giscus, then create the file src/components/GiscusComments.tsx:
import { useColorMode } from \"@docusaurus/theme-common\";
import useDocusaurusContext from \"@docusaurus/useDocusaurusContext\";
import Giscus from \"@giscus/react\";
import React from \"react\";
export default function GiscusComments() {
\tconst {
\t\tsiteConfig: {
\t\t\tcustomFields: {
\t\t\t\tgiscusRepo,
\t\t\t\tgiscusRepoId,
\t\t\t\tgiscusCategory,
\t\t\t\tgiscusCategoryId,
\t\t\t},
\t\t},
\t} = useDocusaurusContext();
\tconst { colorMode } = useColorMode();
\tif (
\t\ttypeof giscusRepo !== \"string\" ||
\t\ttypeof giscusRepoId !== \"string\" ||
\t\ttypeof giscusCategory !== \"string\" ||
\t\ttypeof giscusCategoryId !== \"string\"
\t) {
\t\treturn null;
\t}
\treturn (
\t\t<Giscus
\t\t\trepo={giscusRepo as `${string}/${string}`}
\t\t\trepoId={giscusRepoId}
\t\t\tcategory={giscusCategory}
\t\t\tcategoryId={giscusCategoryId}
\t\t\tmapping=\"pathname\"
\t\t\tstrict=\"0\"
\t\t\treactionsEnabled=\"1\"
\t\t\temitMetadata=\"0\"
\t\t\tinputPosition=\"bottom\"
\t\t\ttheme={colorMode}
\t\t\tlang=\"en\"
\t\t/>
\t);
}
I used Docusaurus' custom fields to retrieve Giscus configuration from Docusaurus' config (itself retrieving these values using dotenv)
In order to add the Giscus component to our blog posts, we are going to use Docusaurus' swizzling method to wrap one component of the template (read about swizzling here):
\nnpm run swizzle @docusaurus/theme-classic BlogPostItem --wrap
This command creates a new file:
\nsrc/theme/BlogPostItem/index.js
which we can directly rename to .tsx:
src/theme/BlogPostItem/index.tsx
Now we need to restart Docusaurus' dev server, in order for it to take the new custom component into account.
This file is a wrapper for the BlogPostItem component. We can very easily add our new GiscusComments component just below it:
import useIsBrowser from \"@docusaurus/useIsBrowser\";
import GiscusComments from \"@site/src/components/GiscusComments\";
import BlogPostItem from \"@theme-original/BlogPostItem\";
import React from \"react\";
const POST_REGEX = /^\\/blog\\/.+$/;
export default function BlogPostItemWrapper(props) {
\tconst isBrowser = useIsBrowser();
\treturn (
\t\t<>
\t\t\t<BlogPostItem {...props} />
\t\t\t{isBrowser && window.location.pathname.match(POST_REGEX) && (
\t\t\t\t<>
\t\t\t\t\t<div style={{ marginTop: \"32px\" }} />
\t\t\t\t\t<GiscusComments />
\t\t\t\t\t<div style={{ marginTop: \"-24px\" }} />
\t\t\t\t</>
\t\t\t)}
\t\t</>
\t);
}
pathname matches /blog/... to not show the Giscus component below all the posts on the main listing page (/blog).isBrowser is to prevent evaluating window at build time, which would creates an error.Last thing, to be done once your local testing is finish, is to add a file giscus.json at the root of the repository to prevent other websites from showing your discussions:
{
\t\"origins\": [\"https://<your-domain>\"]
}
Giscus will stop showing on your localhost:3000 after this file is committed.
The site is deployed on very push to the main branch. The code should be self-explanatory with enough knowledge on GitHub Actions and GitHub Pages.
![\"Git](\"https://zwyx.dev/assets/images/git-hash-miner-b17862480cfb6c1f69e91a500df618c7.webp\")
Following the same principle that Bitcoin uses for its proof of work, we can \"mine\" our Git commit hashes too!
\n\nTo be accepted in the Bitcoin blockchain, the numerical value of a block's hash needs to be lower than a certain number. This make the hash starting with some zeros. This number is regularly reduced, as computers get more powerful; the smaller the number, the harder it is to find a winning hash.
We can do the same with Git commit hashes: mine them to make them start with a particular prefix. Or end with a particular suffix, or any other rule we'd like.
\nRoughly, when a commit is created, Git take these details:
\nand generates a SHA-1 hash with them. That's the commit hash.
\nTo \"mine\" a commit hash, we need to generate multiple hashes until we find one that respects our rule (for instance, starts with a particular prefix). But to make each hash different than the previous one, we need to change something in the details listed above.
I made the package git-hash-miner, which appends a hexadecimal number to the committer name of the last commit, regenerates the SHA-1 hash of the commit details, and continues by incrementing the hexadecimal number at each round until a winning hash is found.
Once it is found, git-hash-miner can automatically amend the commit to add the hexadecimal number to the committer name, and let Git handle the commit and generate the SHA-1, which will be the winning one found just before.
The committer's name is usually not shown by git clients, so it's not an issue to have it modified.
\nAnd even when it's shown, by Sublime Merge for instance, I believe it's not a big deal to have the committer's name followed by a bunch of hexadecimal digits:
\ngit-hash-miner:npm i -g git-hash-miner
gmr [--auto-amend|-a] <target>
where target is the prefix we want the commit hash to start with, and -a automatically amends the commit if the target is found. Do some tests without -a first.
Example: the command gmr -a badc0de will search for a commit hash starting with badc0de then automatically amend the previous commit once it's found.
git-hash-miner creates a worker for each CPU core on your machine. Roughly, you should be able to mine a hash with a prefix of up to 6 or 7 characters in a few minutes.
I added git-hash-miner to the file ~/.nvm/default-packages, so nvm automatically installs it when I install a new version of Node.
Note that there are other projects of this kind around the internet, some of them more performant as they use GPUs. They are, however, more complex to install than git-hash-miner, which is a simple Node script.
Also note that at the moment, if you sign your commits, then your signature is dropped when using git-hash-miner.
Have fun mining!
", "url": "https://zwyx.dev/blog/git-hash-miner", "title": "Git Hash Miner: mine your commit hashes!", "summary": "Following the same principle that Bitcoin uses for its proof of work, we can \"mine\" our Git commit hashes too!", "date_modified": "2022-03-05T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "git", "commit", "hash" ] }, { "id": "https://zwyx.dev/blog/google-authenticator-export-format", "content_html": "If you use Google Authenticator and scan QR codes to create new Time-based One-Time Passwords, you might have noticed that their names are sometimes in the form Issuer (Account name). Google Authenticator allows to rename the Account name part, but not the Issuer.
The following explains how to rename the Issuer, or even get rid of it.
The Google Protocol Buffers tool, which can be found here, or in this repository.
\nThe OtpMigration.proto file present here — thank you to the author — or here.
A way to scan and create QR codes — zbarcam and qrencode for instance.
In Google Authenticator settings, export your accounts. The app will display a QR code containing your TOTP data encoded with Protocol Buffers and URL encoded base64. If you have lots of accounts, then multiple QR codes will be created.
\nUse the next command with one QR code at a time.
\nI use ZSH. You might have to tweak the commands if you use a different shell.
\nzbarcam | \\
\tsed 's/QR-Code://' | \\
\tsed 's/otpauth-migration:\\/\\/offline?data=//' | \\
\tsed -e 's/%2B/+/ig' -e 's/%2F/\\//ig' -e 's/%3D/=/ig' | \\
\tbase64 -d | \\
\tprotoc --decode=MigrationPayload OtpMigration.proto \\
\t> secrets
If you retrieve the data from the QR code in another way, you can replace the first line by:
\n# Note the space before `echo`, it prevents the line
# to be saved in the command history, as it contains secret data
echo \"<qr-code-data>\" | \\
Now, you can open the secrets file and edit it as you want. For each entry, you can rename the issuer, or delete it.
Then run the following to recreate a QR code and display it on your screen, which you will scan with Google Authenticator using the \"Import accounts\" feature present in the settings.
\ncat secrets | \\
\tprotoc --encode=MigrationPayload OtpMigration.proto | \\
\tbase64 -w 0 | \\
\tsed -e 's/+/%2B/ig' -e 's/\\//%2F/ig' -e 's/=/%3D/ig' | \\
\tsed 's/^/otpauth-migration:\\/\\/offline?data=/' | \\
\txargs echo | \\
\tqrencode -t utf8 -o -
Keep in mind that this data is as secret as your passwords. Do not play with QR codes in a public place where you could be seen by a security cameras, or people with phones.
![\"Tree](\"https://zwyx.dev/assets/images/branches-1bd3552051ab477a198c0f99fce33fd2.webp\")
Reduce the amount of branches without necessarily deleting them
\n\nThis article contains ideas and suggestions for an more advanced use of Git; it's intended for people who already know its basic usage.
When working on a code base, alone or with a team, we can end up with a lot of branches that are inactive. They are experiments that have never been completed, for instance.
\nThe presence of these forgotten branches can be bothering:
\ngit checkout will be cluttered;However, deleting these branches might not be possible. Some could be useful in the future. Some people in your team might want to delete them while others want to keep them.
\nA solution is to “archive” these branches by storing them separately from the normal git branches. The archived branches won't show up in git branch anymore, but they will stay available if someone wants to resume work on them.
Git stores local branches in refs/heads. For instance, a branch called branch will be in refs/heads/branch.
Remote branches are in refs/remote/<remote-name>. For instance, refs/remote/origin/branch. There are also refs/tags, refs/stash, refs/notes.
To archive a branch, we can place them in a newly created ref, for instance: refs/experiments.
If we are in a team we can add a sub-level with the name of the developers: refs/experiments/<developer-name>.
The following sections explains the commands allowing us to achieve this.
\nSave the branch in the experiments ref:
git update-ref refs/experiments/alice/branch branch
Push the experiment to the remote:
\ngit push origin refs/experiments/alice/branch
Delete the original branch, locally and on the remote:
\ngit branch -d branch
git push -d origin branch
Create a branch that points to the same commit than the experiment:
\ngit checkout -b branch refs/experiments/alice/branch
Optional, delete the experiment, locally and on the remote:
\ngit update-ref -d refs/experiments/alice/branch
git push -d origin refs/experiments/alice/branch
View all experiments:
\ngit for-each-ref | grep refs/experiments
Push all experiments to the remote:
\ngit push origin \"refs/experiments/*\"
Fetch all experiments present on the remote:
\ngit fetch origin \"refs/experiments/*:refs/experiments/*\"
(or:
\ngit fetch origin \"+refs/experiments/\\*:refs/experiments/\\*\"
but careful: this will erase all experiments present locally)
\nSee everything that's in refs on a remote repository:
\ngit clone --mirror <repo>
cd <repo>
git for-each-ref
Doing this on a GitHub repository which has had pull requests, you will notice that GitHub creates refs/pull and stores all pull requests in it.
\n![\"Password](\"https://zwyx.dev/assets/images/main-47cd28480cb4393dd05f6181fe258cf5.webp\")
In this post, we will use pass to set up a complete, shared and segmented, professional password store.
This post contains ideas and suggestions for a more advanced use of pass; it's intended for people who already know its basic usage.
Before all, why do I use a trivial command line tool instead of one of the many fancy password managers available?
\nBecause I believe critical things need to be kept simple.
\nThey need to be open source and have proven themselves by being maintained, audited, and used by many.
\nEven a serious security company is capable of inadvertently exposing a backdoor on their users' machines allowing remote code execution and the theft of your passwords (← I really recommend the reading of this story).
pass is one bash script relying on GPG. Both tools are open and have been used extensively for a while.
There are some GUIs for pass, some browser extensions, mobile apps, etc. but choose them carefully: the more we add, the larger the attack surface becomes.
I use Termux on Android, which provides pass in its packages. It doesn't autofill credentials, but apps and websites are good at remembering who you are these days, so I don't need to log in often.
First, a little tweak for the retrieval of a password.
\nThe default command — pass -c <password-name> — outputs the password in the clipboard and clears it after 45 seconds.
However, I have a clipboard manager that keeps everything I put in the clipboard.
\nTo prevent passwords from being recorded, I wrote a command that outputs them in the X selection instead of the clipboard. To paste them, I click the middle mouse button, instead of using Ctrl-V.
\nTo do that, add the following in your .zshrc (you might have to make some modifications if you're using a different shell):
p() {
\t# Insert the password into the X selection
\t# (also called primary, see `man xclip`)
\tpass $1 | head -n 1 | tr -d \"\\n\" | xclip
\t# Countdown
\tfor i in {5..1}; do
\t\tprintf \"\\r$i\"
\t\tsleep 1
\tdone
\t# Clear the selection
\techo -n \"\" | xclip
\techo \"\\r✔\"
}
# Associate the completer of `pass` to the command `p`, allowing
# the Tab key to be used with `p` to autocomplete the passwords names
compdef _pass p
# Note: use `p` only to retrieve an existing password,
# not with other `pass` commands (`generate`, etc.)
Here it is in action:
\n\n![\"The](\"https://zwyx.dev/assets/images/p-59e0936ad3963b402dad61fbe18813b6.gif\")
It's possible to have two completely separated password stores by creating a new command for the second one. The new command, passpro for instance, will use a different directory:
passpro() {
\t# Set a different password store directory,
\t# then run `pass` with all the arguments received by `passpro`
\tPASSWORD_STORE_DIR=~/.password-store-pro pass $@
}
_passpro() {
\t# Same idea for the completer
\tPASSWORD_STORE_DIR=~/.password-store-pro _pass
}
# Then we associate the two
compdef _passpro passpro
# And we can have the same short command to retrieve a password:
pp() {
\tPASSWORD_STORE_DIR=~/.password-store-pro p $@
}
compdef _passpro pp
Having two different pass commands is my preference, but there are other ways to have multiple stores. For instance, you could make use of .gitignore or git submodules to have the second store inside the first one.
We can share a password store with many people, while still being able to fine tune who has access to what.
\ndevs subfolder and a support subfolder:~/.password-store-pro
├── devs
│ ├── databasePassword
│ ├── serverSshKey
│ └── stackCredentials
└── support
├── supportPlatformPassword
└── supportEmailPassword
.gpg-id file listing the PGP key UIDs of the persons having access to the content of this subfolder:~/.password-store-pro
├── devs ┌───────────────────────────┐
│ ├── .gpg-id → │ Alice <alice@example.com> │
│ │ │ Bob <bob@example.com> │
│ │ └───────────────────────────┘
│ ├── databasePassword \\
│ ├── serverSshKey > Each file is encrypted
│ └── stackCredentials / for Alice and Bob
└── support ┌───────────────────────────┐
├── .gpg-id → │ Alice <alice@example.com> │
│ │ Carl <carl@example.com> │
│ │ David <david@example.com> │
│ └───────────────────────────┘
├── supportPlatformPassword \\ Each file is encrypted for
└── supportEmailPassword / Alice, Carl and David
And that's basically it.
\nThere are a few other things to help us:
\nIn the root directory, a .public-keys folder contains the public PGP keys of all the persons having access to the store. That allows the creation of new passwords that will be decryptable by the persons/teams we want.
The .gpg-id file in the root directory lists who has access to the secrets in this directory — and any subfolder which doesn't have its own .gpg-id. We don't use it in this example.
Finally, the bash script encrypt.sh is used to display detailed information about the password store, and to reencrypt it when a new user is given access to the store. Indeed, when a new user is added, every passwords he will have access to needs to be reencrypted for his public key. This process is explain later in this article.
So here's our complete, shared and segmented, professional password store:
\n~/.password-store-pro
├── .public-keys
│ ├── alice.asc
│ ├── bob.asc
│ ├── carl.asc
│ └── david.asc
├── devs ┌───────────────────────────┐
│ ├── .gpg-id → │ Alice <alice@example.com> │
│ │ │ Bob <bob@example.com> │
│ │ └───────────────────────────┘
│ ├── databasePassword
│ ├── serverSshKey
│ └── stackCredentials
├── support ┌───────────────────────────┐
│ ├── .gpg-id → │ Alice <alice@example.com> │
│ │ │ Carl <carl@example.com> │
│ │ │ David <david@example.com> │
│ │ └───────────────────────────┘
│ ├── supportPlatformPassword
│ └── supportEmailPassword
├── .gpg-id
└── encrypt.sh
The content of encrypt.sh can be found here.
\nNow, let's see how to use the password store.
\nNow that we have the structure of our shared store, let's create a password.
\ngpg --import ~/.password-store-pro/.public-keys/*.asc
gpg --edit-key \"<key-uid>\"
gpg> trust
Your decision? 5
gpg> quit
pass git, for instance:passpro git checkout -b new-password
passpro generate -n devs/cloudPlatformCredentials 20
As stated before, when a new user is added, every passwords he will have access to needs to be reencrypted for his public key.
\nFirst, we add the user's public key to the .public-keys directory.
Then, we import it to our keyring:
\ngpg --import .public-keys/*.asc
gpg --list-keys
For instance, the uid can be: Elie <elie@example.com>
gpg --edit-key \"Elie <elie@example.com>\"
gpg> trust
Your decision? 5
gpg> quit
.gpg-id file of each subfolder the new user needs to have access to; for instance, let's say that the new user is a developer, we add the key's uid in devs/.gpg-id:Alice <alice@example.com>
Bob <bob@example.com>
Elie <elie@example.com>
./encrypt.sh devs
This will list the persons for whom the devs subfolder will be encrypted, and ask you to confirm:
Password store root directory:
\t'/home/user/.password-store-pro'
1 subfolders will be encrypted.
'devs' will be encrypted for:
\tAlice <alice@example.com>
\tBob <bob@example.com>
\tElie <elie@example.com>
Proceed? [y/N]
./encrypt.sh can also be run without any arguments, to reencrypt the whole store. However, remember that you need access to a password in order to be able to encrypt it for a new user, as you need to decrypt it first.
Decrypting passwords stays as easy than it is with a personal password store. Note that Windows users who only need read access to the passwords can install Gpg4win - instead of a non-official version of Pass.
I hope you enjoyed this article, have fun with Pass!
", "url": "https://zwyx.dev/blog/shared-password-stores", "title": "Multiple shared password stores with Git and pass", "summary": "Use pass to set up a complete, shared and segmented, professional password store.", "date_modified": "2021-06-27T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "password", "password manager", "pass" ] }, { "id": "https://zwyx.dev/blog/react-nfc", "content_html": "This article has been written in 2019. I stopped working with NFC on mobile a few years later.
![\"React](\"https://zwyx.dev/assets/images/react-nfc-2df0d3ca1a564f805081146463d38c26.webp\")
Ionic Capacitor and Apache Cordova are two common wrappers to create a hybrid mobile application from a web application. The main advantage over a native mobile app is the re-usability of the code — and the development languages being HTML, CSS, and JavaScript, if we like them.
\n\nHowever, hybrid apps are not always the best choice and some research is necessary to determine which technology is best for a particular purpose.
\nOne thing to keep in mind though, is that using a mobile wrapper to create a hybrid app which is nothing more than a shell for a website, is not well accepted.
Let's say we have a nice responsive web app which works already great on a mobile browser, and which would be even greater if it could use NFC features on mobile devices.
\nAs we cannot access NFC from a web browser (yet), we need to create a mobile app.
\nAs our web app is already designed to be displayed well on small screens (responsive), creating a hybrid mobile app from it will be much easier and quicker than recreating a native mobile app from scratch (or more than one: one for each platform we want to support…).
\nTo demonstrate this, we will start by creating a React app — with TypeScript — add the PhoneGap NFC plugin, then wrap our app with Capacitor or Cordova. We will need Node and npm (use a Node version manager, like nvm), the Android SDK and Android Studio.
\nFirst, we create a new React app by running:
\nnpx create-react-app react-nfc --typescript
npx allows to execute npm package binaries without having to install them.
Then we jump in the newly created folder and install PhoneGap NFC and its types for TypeScript:
\ncd react-nfc
npm i phonegap-nfc
npm i --save-dev @types/phonegap-nfc
The PhoneGap NFC stuff will be accessible globally, so we don't need any imports in our code.
\nNow we open src/App.tsx and we replace its content by the following code, which is going to initialise NFC, invite the user to open the phone settings if NFC is not enabled, and read the content of an NFC tag (PhoneGap NFC offers plenty of other features documented here):
import React from \"react\";
import \"./App.css\";
/** Type for the possible steps of the app */
type TStep =
\t| \"initializing\"
\t| \"noNfc\"
\t| \"nfcNotEnabled\"
\t| \"waitingForNfcEnabled\"
\t| \"waitingForTag\"
\t| \"cancelled\"
\t| \"tagRead\";
const App: React.FC = () => {
\tconst [step, setStep] = React.useState<TStep>(\"initializing\");
\tconst [tagContent, setTagContent] = React.useState(\"\");
\t// Initialize NFC when the app is started
\tReact.useEffect(initializeNfc, []);
\tfunction initializeNfc() {
\t\t// If nfc is undefined, NFC is not available on this device, or
\t\t// the app is running in a web browser
\t\tif (typeof nfc !== \"undefined\") {
\t\t\t// Register an event listener
\t\t\tnfc.addNdefListener(
\t\t\t\tonNdefEvent, // The callback function for the event listener
\t\t\t\t() => setStep(\"waitingForTag\"), // Success → We're waiting for an event
\t\t\t\t() => setStep(\"nfcNotEnabled\"), // Error → NFC must not be enabled
\t\t\t);
\t\t} else {
\t\t\tsetStep(\"noNfc\");
\t\t}
\t}
\tfunction onGoToSettingsClick() {
\t\tif (typeof nfc !== \"undefined\") {
\t\t\t// Ask the device to open the NFC settings for the user
\t\t\tnfc.showSettings(
\t\t\t\t() => setStep(\"waitingForNfcEnabled\"),
\t\t\t\t() => alert(\"An error occurred while trying to open the NFC Settings.\"),
\t\t\t);
\t\t}
\t}
\tfunction onNdefEvent(e: PhoneGapNfc.TagEvent) {
\t\t// Unregister the event listener
\t\tnfc.removeNdefListener(onNdefEvent);
\t\tsetTagContent(
\t\t\t// Retrieve the payload of the tag and decode it
\t\t\t// https://www.oreilly.com/library/view/beginning-nfc/9781449324094/ch04.html
\t\t\tndef.textHelper.decodePayload(
\t\t\t\t(e as PhoneGapNfc.NdefTagEvent).tag.ndefMessage[0].payload,
\t\t\t),
\t\t);
\t\tsetStep(\"tagRead\");
\t}
\tfunction onStopClick() {
\t\tif (typeof nfc !== \"undefined\") {
\t\t\t// Unregister the event listener
\t\t\tnfc.removeNdefListener(onNdefEvent);
\t\t}
\t\tsetStep(\"cancelled\");
\t}
\treturn (
\t\t<div className=\"nfc\">
\t\t\t{step === \"initializing\" ? (
\t\t\t\t<div>Initializing...</div>
\t\t\t) : step === \"noNfc\" ? (
\t\t\t\t<div>
\t\t\t\t\tThe device you are using doesn't appear to have NFC; or, the
\t\t\t\t\tPhoneGap-NFC plugin hasn't been set up correctly.
\t\t\t\t</div>
\t\t\t) : step === \"nfcNotEnabled\" ? (
\t\t\t\t<div>
\t\t\t\t\t<div>
\t\t\t\t\t\tNFC is not enabled on your device. Click the button bellow to open
\t\t\t\t\t\tyour device's settings, then activate NFC.
\t\t\t\t\t</div>
\t\t\t\t\t<button onClick={onGoToSettingsClick}>Go to NFC Settings</button>
\t\t\t\t</div>
\t\t\t) : step === \"waitingForNfcEnabled\" ? (
\t\t\t\t<div>
\t\t\t\t\t<div>Please click the button below once you have enabled NFC.</div>
\t\t\t\t\t<button onClick={initializeNfc}>Initialize NFC Reader</button>
\t\t\t\t</div>
\t\t\t) : step === \"waitingForTag\" ? (
\t\t\t\t<div>
\t\t\t\t\t<div>Scan a NFC Tag to see its content</div>
\t\t\t\t\t<button onClick={onStopClick}>Stop NFC Reader</button>
\t\t\t\t</div>
\t\t\t) : step === \"tagRead\" ? (
\t\t\t\t<div>
\t\t\t\t\t<div>Tag scanned! Here it's content:</div>
\t\t\t\t\t<div>{tagContent}</div>
\t\t\t\t\t<button onClick={onStopClick}>Stop NFC Reader</button>
\t\t\t\t</div>
\t\t\t) : (
\t\t\t\t<div>
\t\t\t\t\t<div>Bye!</div>
\t\t\t\t</div>
\t\t\t)}
\t\t</div>
\t);
};
export default App;
We add some styling in App.css:
.nfc {
\theight: 100vh;
\twidth: 100vw;
\tbackground-color: #21252b;
\tcolor: #abb2bf;
\tdisplay: flex;
\tflex-direction: column;
\tjustify-content: center;
\ttext-align: center;
}
.nfc div {
\tpadding: 8px 16px;
}
button {
\tmargin: 16px;
\tborder: none;
\tborder-radius: 3px;
\tpadding: 8px 12px;
\tbackground-color: #61afef;
\tcolor: #21252b;
\tcursor: pointer;
}
We can now build the project:
\nnpm run build
And that's it for our app. The full project can be found here.
\nNow, we are going to wrap our web app to create an Android one. Once with Capacitor, once with Cordova (this is twice the same thing, we only do it to show case the two solutions).
\nWe run the following commands to install Capacitor, initialise it for our web app (our built app files are located in the build folder), and add the Android platform to our project:
npm i @capacitor/core @capacitor/cli
npx cap init --web-dir build
npx cap add android
If an error occurs, see the first point in the Notes section below.
We can now start Android Studio, open the newly created android folder as a project, wait for the scripts execution to finish, then click Run → Run 'app' to execute our app on our device.
![\"Our](\"https://zwyx.dev/assets/images/nfc-unavailable-e22021c93b3afd41473a675479f36c9c.webp\")
From now on, if we make changes to our web app, we just need to run the following two commands to rebuild the app and update the Capacitor project:
\nnpm run build
npx cap sync
(If Android Studio is a bit lost, Project → Rebuild might help — if it is still lost, closing the project and reopen the android folder should work. Likewise, unplugging and plugging back the device might sometimes help is the Android debugger doesn't recognise it.)
The app logo and splash screen are located in the android/app/src/main/res folder.
To create a new logo, in Android Studio, right click on the res folder then select New → Image Asset.
To change the splash screen, generate the images using a tool like this one, then place them in the res folder.
Cordova requires a few tweaks in the web app itself.
\nFirst, we need to replace the following line in src/index.tsx:
ReactDOM.render(<App />, document.getElementById(\"root\"));
by:
\ndocument.addEventListener(
\t\"deviceready\",
\t() => ReactDOM.render(<App />, document.getElementById(\"root\")),
\tfalse,
);
Then, we need to add the following parameter in package.json — at the same level of name, version, etc.:
\"homepage\" : \"./\",
We can now rebuild the app:
\nnpm run build
Now, we need to set up our environment:
\nANDROID_SDK_ROOT variablebin folder of graddle in the PATHReplace the <...> in the following commands before running them:
export ANDROID_SDK_ROOT=<path-to-the-android-sdk>
export PATH=$PATH:<path-to-android-studio>/gradle/gradle-<version>/bin
chmod +x <path-to-android-studio>/gradle/gradle-<version>/bin/gradle
We can now create our Cordova project:
\nnpx cordova create Cordova com.example ReactNfc
cd Cordova
npx cordova plugin add phonegap-nfc
npx cordova platform add android
If an error occurs, see the second point in the Notes section below.
We place our web app in the Cordova project by copying the content of the build folder in the Cordova/www folder (after having deleted everything in Cordova/www). We also need to add the following line in index.html:
<script src=\"cordova.js\"></script>
As index.html is minified, to make it simple, we just paste this line at the end of the file, just before the </body></html> tags. So the file ends by:
<script src=\"cordova.js\"></script></body></html>
That's it! Cordova requires a few more tweaks than Capacitor, but we now just have to run:
\nnpx cordova run
to launch our app on our device!
\nHopefully this article has given you the basics to create a hybrid mobile app from a web app and use a native feature with it such as NFC. Happy coding!
\nOh, and if you are going to use a package often, you might want to install it instead of using npx, especially Cordova which can take a while to start. It's recommended to install it locally in the project folder.
To do so, first create the Cordova project with npx then jump in the Cordova folder and run:
npm i cordova
Now open the file package.json — still in the Cordova folder — and add the following script in the \"scripts\" section:
\"cordova\": \"node_modules/cordova/bin/cordova\"
You can now run, for instance:
\nnpm run cordova run
To install Cordova globally, you can run:
\nsudo npm install -g cordova
node_modules/@capacitor/cli/dist/android/update.js and replace line 208 from:const pathParts = getPathParts(configElement.$.parent);
to:
\nconst pathParts = getPathParts(
\tconfigElement.$.parent || configElement.$.target,
);
This problem has been fixed already, it will probably be pushed on NPM with the next update of Capacitor.
\nCordova/plugins/phonegap-nfc/plugin.xml and comment out the following section (starting at line 39):<edit-config file=\"AndroidManifest.xml\" target=\"/manifest/uses-sdk\" mode=\"merge\">
<uses-sdk android:minSdkVersion=\"19\" />
</edit-config>
then delete the folder Cordova/platforms/android and execute again:
npx cordova platform add android
This error has been identified.
", "url": "https://zwyx.dev/blog/react-nfc", "title": "NFC on Android with React and TypeScript using Capacitor or Cordova", "summary": "Hybrid mobile apps are a great way to add native mobile features to an existing responsive web app.", "date_modified": "2019-10-05T00:00:00.000Z", "author": { "name": "Alex", "url": "https://github.com/Zwyx" }, "tags": [ "nfc", "typescript", "react", "capacitor", "cordova" ] } ] }