251 lines
9 KiB
Markdown
251 lines
9 KiB
Markdown
---
|
|
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
|
|
```
|
|
|
|
## Ignoring Files
|
|
|
|
### How can I configure ignored files?
|
|
|
|
By default, yadm is configured to
|
|
[ignore untracked files](#how-can-i-display-untracked-files-with-a-yadm-status-command)
|
|
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.
|