Debian Codegraph @

docs/config/config-profiles.md

raw
1 # Profiles entry
2
3 The **profiles** entry (mandatory) contains a YAML object with sub-objects for the profiles for the different dotfiles that need to be managed. The entries in the sub-objects are as follows:
4
5 Entry | Description
6 -------- | -------------
7 `dotfiles` | The dotfiles associated with this profile
8 `import` | List of paths containing dotfile keys for this profile (absolute path or relative to the config file location; see [Import profile dotfiles from file](config-profiles.md#profile-import-entry)).
9 `include` | Include all elements (dotfiles, actions, (dyn)variables, etc) from another profile (See [Include dotfiles from another profile](config-profiles.md#profile-include-entry) and [meta profiles](../howto/group-hosts.md))
10 `variables` | Profile-specific variables (See [Variables](config-file.md#variables))
11 `dynvariables` | Profile-specific interpreted variables (See [Interpreted variables](config-dynvars.md))
12 `actions` | List of action keys that need to be defined in the **actions** entry below (See [actions](config-actions.md))
13
14 ```yaml
15 <some-profile-name-usually-the-hostname>:
16 dotfiles:
17 - <some-dotfile-key-name-defined-above>
18 - <some-other-dotfile-key-name>
19 - ...
20 ## Optional
21 include:
22 - <some-other-profile>
23 - ...
24 variables:
25 <name>: <value>
26 dynvariables:
27 <name>: <value>
28 actions:
29 - <some-action>
30 - ...
31 import:
32 - <some-path>
33 - ...
34 ```
35
36 ## Profile include entry
37
38 If one profile is using the entire set of another profile, one can use
39 the `include` entry to avoid redundancy.
40
41 Note that everything from the included profile is made available
42 (actions, variables/dynvariables, etc). See also an example in
43 [meta profiles](../howto/group-hosts.md).
44
45 For example:
46 ```yaml
47 profiles:
48 host1:
49 dotfiles:
50 - f_xinitrc
51 include:
52 - host2
53 host2:
54 dotfiles:
55 - f_vimrc
56 ```
57 Here profile *host1* contains all the dotfiles defined for *host2* plus `f_xinitrc`.
58
59 For more advanced use-cases, variables
60 ([variables](config-variables.md) and [dynvariables](config-dynvars.md))
61 can be used to specify the profile to include in a profile:
62
63 For example:
64 ```yaml
65 variables:
66 var1: "john"
67 dynvariables:
68 d_user: "echo $USER"
69 profiles:
70 profile_john:
71 dotfiles:
72 - f_john_dotfile
73 profile_bill:
74 dotfiles:
75 - f_bill_dotfile
76 p1:
77 include:
78 - "profile_{{@@ d_user @@}}"
79 p2:
80 include:
81 - "profile_{{@@ var1 @@}}"
82 ```
83
84 Note that profiles cannot include other profiles defined above in
85 the import tree (for example, when a profile exists in another file and is imported using `import_configs`).
86
87 ## Profile import entry
88
89 A profile's dotfiles list can be loaded from external files
90 by specifying their paths in the config entry `import` under the specific profile.
91
92 The paths can be absolute or relative to the config file location.
93
94 `config.yaml`
95 ```yaml
96 dotfiles:
97 f_abc:
98 dst: ~/.abc
99 src: abc
100 f_def:
101 dst: ~/.def
102 src: def
103 f_xyz:
104 dst: ~/.xyz
105 src: xyz
106 profiles:
107 p1:
108 dotfiles:
109 - f_abc
110 import:
111 - somedotfiles.yaml
112 ```
113
114 `somedotfiles.yaml`
115 ```
116 dotfiles:
117 - f_def
118 - f_xyz
119 ```
120
121 Variables can be used in `import`, what allows to do something like:
122 ```yaml
123 import:
124 - profiles.d/{{@@ profile @@}}.yaml
125 ```
126
127 ## Profile variables entry
128
129 Profile variables will take precedence over globally defined variables.
130 This means that you could do something like this:
131 ```yaml
132 variables:
133 git_email: [email protected]
134 dotfiles:
135 f_gitconfig:
136 dst: ~/.gitconfig
137 src: gitconfig
138 profiles:
139 work:
140 dotfiles:
141 - f_gitconfig
142 variables:
143 git_email: [email protected]
144 private:
145 dotfiles:
146 - f_gitconfig
147 ```
148
149 ## Profile actions entry
150
151 A profile action can be either a `pre` or `post` action (see [actions](config-actions.md)).
152 These are executed before any dotfile installation (for `pre`) and after all dotfile installations (for `post`)
153 only if at least one dotfile has been installed.