yadm/_docs/060_faq.md

---
title: "Frequently Asked Questions"
permalink: /docs/faq
#{% include toc title="Questions" %}
---

## Usage

### I just cloned my repository and conflicting data was overwritten. Why?

Prior to cloning your repository, files managed by **yadm** already existed. For
example, imagine you are logged into a system and `$HOME/.bash_profile` already
exists. If you then clone your **yadm** repository—which also contains
`.bash_profile`—then you will likely get a conflict. Since version 1.07,
**yadm** responds by "stashing" these conflicts. To view the stashed data, you can
run `yadm stash show -p` from within your `$HOME` directory. If you want to
restore the stashed data, you can run `yadm stash apply` from within your
`$HOME` directory.

### 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 `~/.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.


## Encryption

### Can I use **yadm** without **gpg**?

Of course. You only need `gpg` 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 `.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. Files you want encrypted should be added to the file
`.yadm/files.gpg` using the `yadm encrypt` command. Then `.yadm/files.gpg`
should be added to the **yadm** repository. This way, only an encrypted
collection of those files are put into the repository. After cloning or updating
your repository, you can use `yadm decrypt` to extract those files from
`.yadm/files.gpg`. 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 `.yadm/encrypt`, you must re-run `yadm
encrypt` to generate a new version of `.yadm/files.gpg`. Then `.yadm/files.gpg`
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** and **git-crypt**?

There is an experimental version of **yadm** which can use **git-crypt**. You
can find it in the [git-crypt-support branch](
https://github.com/TheLocehiliosan/yadm/commits/git-crypt-support
). See the
[notes](
https://github.com/TheLocehiliosan/yadm/commit/efb7fd16612fe650b1286f0c696696f412772ab3
) in the commit messages of that branch for details.

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