yadm/_docs/110_faq.md

---
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 <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](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 / <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.