yadm/_docs/110_faq.md

title	permalink
Frequently Asked Questions	/docs/faq

{% 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 <NEW-URL>

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 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 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 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.

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

Ignoring Files

How can I configure ignored files?

By default, yadm is configured to ignore untracked files when displaying a status. This does not prevent you from adding untracked files. However, if you would like to prevent some files from being added accidentally, you can configure them to be ignored.

If you add a .gitignore file to your $HOME directory (or subdirectories) you can have those patterns ignored by yadm. This works exactly like it does for Git. Be sure to add these .gitignore files to your repo, so they can be synced along with your other configurations.

Another option is to add patterns to $HOME/.local/share/yadm/repo.git/info/exclude. If you use this file, be sure to add your patterns above any yadm-auto-excludes line, as all lines below this can be overwritten by yadm when encrypting data.

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 --yadm-dir /etc/yadm --yadm-data /etc/yadm/data"

# initialize the yadm repo using the worktree of "/"
sysyadm init -w /

# or clone the yadm repo using the worktree of "/"
sysyadm clone -w / <url>

# 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.