yadm/_docs/060_faq.md

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

## Usage

### I just cloned my repository, but `yadm status` shows conflicts. 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. You must decide how to
resolve that conflict. Perhaps you don't want to overwrite the current version.
You might want merge the content together in some way. This can be resolved the
same way you resolve any Git conflict.

If you merely want to forcefully overwrite all the managed files using the HEAD
revision of your repository, you probably want to run

```
yadm reset --hard HEAD
```

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

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