mirror of
https://github.com/TheLocehiliosan/yadm
synced 2024-10-27 20:34:27 +00:00
186 lines
6.9 KiB
Markdown
186 lines
6.9 KiB
Markdown
---
|
|
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.
|
|
|
|
## 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**?
|
|
|
|
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.
|