--- title: "Frequently Asked Questions" permalink: /docs/faq # TOC levels is dictated by toc_levels in _config.yml # Update to front-matter TOC after upgrading MMistakes --- {% include toc title="Categories" %} ## Usage ### While committing I got the message, _"Please tell me who you are"_. Why? Whenever a Git commit is generated, Git requires information about the author of the commit. This can be configured via the `git config` command. Usually the best approach is to configure this information globally, and then manage your global Git configuration via yadm. This allows the configuration to follow you wherever your dotfiles live. ``` git config --global "user.email" "your-email@domain" git config --global "user.name" "Your Name" yadm add ~/.gitconfig ``` However, if you want commits to your yadm repo to use a different author, you can configure these settings in the yadm repo itself. ``` yadm gitconfig "user.email" "alternate-email@domain" yadm gitconfig "user.name" "Alternate Name" ``` Note: Configuring these settings directly in the yadm repo will require you to configure it each time you clone the repo. ### How can I display untracked files with a `yadm status` command? By default, yadm is configured to ignore untracked files when displaying a status. You can use the `-u` paramter on the status command to alter how untracked files are treated. `-unormal` will show untracked files and directories. ``` yadm status -unormal ``` If you want to change the default treatment, you can change this configuration on the yadm repository itself. ``` yadm gitconfig --unset status.showUntrackedFiles ``` ### How can I stage all modified files at once? Just as with Git, you can use the `add` command. ``` yadm add -u :/ ``` (Starting with Git 2.0, the `:/` is not necessary) ### How can I change the URL of my remote yadm repository? This is done the same way you change the URL of any Git repository. ``` yadm remote set-url origin ``` This could be useful if you manage your ssh keys in the yadm repository. That could make it difficult to initially clone the repository using the `ssh` protocol. You can start by cloning the repository using the `https` protocol (and providing a password), and then change the repository's URL after you've decrypted your ssh keys. ### I've customized yadm configurations (stored in `~/.config/yadm/config`). Should I add that to my repository? Certainly. That is a good way to carry your yadm configurations around (just like the rest of your dotfiles). ### Can you point to any example yadm managed repositories? [This page](examples) contains some examples. ## Bootstrapping ### Do I need to write my bootstrap in Bash? No. Any executable file can be used as a bootstrap. It's up to you to decide what works best. ### I've created a bootstrap program. Should I add that to my repository? Absolutely. That will allow your bootstrap program to be executed each time you clone your repository. Read [bootstrap](bootstrap) for more details. ## Encryption ### Can I use yadm without gpg, openssl, transcrypt or git-crypt? Of course. You only need `gpg`, `openssl`, `transcrypt` or `git-crypt` installed if you plan on using the encrypt/decrypt features. yadm will tell you if it is missing a dependency for any command. ### Should I `yadm add` my `~/.config/yadm/encrypt` file? Yes! This way your configuration for what files should be encrypted will follow you when you clone your repository. ### Should I `yadm add` encrypted files to repository? No, you should not. Instead, add the names (or wildcard patterns) of the files you want encrypted to `~/.config/yadm/encrypt`. Then, use the `yadm encrypt` command to encrypt the matched files which then adds them to `~/.local/share/yadm/archive`. Then, use `yadm add ~/.local/share/yadm/archive` to add this file to the yadm repository. This way, only encrypted versions of those files will be in the repository. After cloning or updating your repository, you can use `yadm decrypt` to extract the encrypted files from `~/.local/share/yadm/archive` into your working copy. See the [encryption help](encryption) for more details. ### I modified an encrypted file, but yadm doesn't show any modifications. Why? If you changed files which are matched by `~/.config/yadm/encrypt`, you must re-run `yadm encrypt` to generate a new version of `~/.local/share/yadm/archive`. Then `~/.local/share/yadm/archive` can be added to a new commit. ### Why do I get the error `Inappropriate ioctl for device` when encrypting. If you get the error `command get_passphrase failed: Inappropriate ioctl for device` when running `yadm encrypt`, gpg is having trouble identifying the tty to use. The environment variable `GPG_TTY` can be used to help gpg out. Export this variable to your shell in your login scripts. ``` export GPG_TTY=$(tty) ``` ### Can I use yadm with transcrypt or git-crypt? Yes, yadm now supports both transcrypt and git-crypt. Read more [here](/docs/encryption#transcrypt--git-crypt). ## Directory Creation ### Why are `.ssh` or `.gnupg` directories being created by yadm? yadm is often used to track private data used by SSH and GnuPG. Because of this, these directories are created with restricted permissions prior to Git operations that could write data to those directories. This is to better protect that sensitive data. If you want to disable that feature, you can set the `auto-private-dirs` configuration by running: ``` yadm config yadm.auto-private-dirs false ``` ## Integrations ### Why does git-cola hang when run via `yadm enter`? `git-cola` tries to display all of the untracked files in a repository. For dotfiles, this is usually a massive list of files. The solution is to configure your repo to have `git-cola` ignore untracked files with the following configuration. ``` yadm gitconfig gui.displayuntracked false ``` ## Unconventional Cases ### Can I use yadm to track system level files? yadm only manages files within the configured worktree (`$HOME` by default). Also, yadm will use the effective user for file ownership just like Git. However, if you want to bend yadm into managing system files, one method is: ``` # create an alias to run yadm for system files alias sysyadm="sudo yadm -Y /etc/yadm" # initialize the yadm repo using the worktree of "/" sysyadm init -w / # or clone the yadm repo using the worktree of "/" sysyadm clone -w / # continue to use sysyadm for managing system files sysyadm add /etc/something.conf sysyadm commit -m 'Add something.conf' ``` Assuming you have "sudo" rights, the `sysyadm` alias will work as if root was using yadm, having the owner be "root", with the ability to manage any file under `/`. If you were only interested in managing files under `/etc`, you could use that as the worktree instead. ## Comparisons ### How does yadm differ from homeshick? yadm and homeshick are both written in Bash, with very limited dependencies. However, homeshick works by symlinking data from a repository working directory into your `$HOME` directory. yadm instead uses your `$HOME` directory _as_ its working directory. homeshick allows for multiple "castles" to be linked into `$HOME`, while yadm is designed to work with a single repository. homeshick requires you to change into the "castle" directory before performing any Git based commands. yadm allows you to perform operations regardless of your location. yadm also includes unique features to encrypt private data, and symlink alternate versions of files based on OS type or hostname. ### How does yadm differ from vcsh? yadm and vcsh both work as a filters for standard Git commands. Both also use your `$HOME` directory _as_ the repository's working directory. However, vcsh is designed to work with multiple repositories, yadm instead uses a single repository. vcsh requires you to specify which repository you want to operate on, while yadm only operates on one. If you want to use Git submodules, you _may_ have trouble using vcsh. This is because only one repository can be the owner of the `.gitmodules` file. yadm also includes unique features to encrypt private data, and symlink alternate versions of files based on OS type or hostname.