Languages: Português Brasileiro
Initially, Dotctrl was created just to control "dotfiles files", however, in the course, it became more than that. Dotctrl is now a maintainer of any file and folder type within its own private repository.
This is too much!
Dotctrl will manage the elements of the user's HOME directory; running on
top of a configuration file (dotctrl.json) that contains the paths to the
origin location of the elements.
All elements managed by Dotctrl are kept in the repository/folder "dotctrl".
See a demo:
- language support: American English and Brazilian Portuguese;
- create (or not) multiple repositories for your elements;
- abandon the creation of huge manual symlinks;
- will store the same path structure as your original location (
$HOME); - manage single or bulk elements;
- restore repository elements to their original location with a single command;
- and much more :)
To work properly, you will first need:
LinuxormacOSPython(v3.9 or recent);Pip(v19.3 or recent) must be installed;Git(v2.0 or recent);- One of this editor vim, nano, emacs or micro must be installed;
It's time to install Dotctrl. To do this, do:
python3 -m pip install dotctrl --userNOTE: If you are installing in the user's local environment, be sure to add the environment variables to the
zshrcfile or.bashrcfile.
After installing the package, you need to create the Dotctrl repository in an empty folder in your choice. We always recommend creating /home or /Users in the root directory, because creating in the user's folder can be lost if user is deleted. With that, see the example below:
Linux:
sudo mkdir -p /home/.dotfiles; cd $_
sudo chown -R $(whoami) /home/.dotfiles
sudo chmod -R 700 /home/.dotfiles
dotctrl initmacOS:
sudo mkdir -p /Users/.dotfiles; cd $_
sudo chown -R $(id -un) /Users/.dotfiles
sudo chmod -R 700 /Users/.dotfiles
dotctrl initYou can bypass all of these commands above using the --auto flag. Dotctrl
will automatically create a base
directory to store the data, however you MUST have sudo permission.
We strongly recommend using this option if you have permission.
dotctrl init --autoThis flag causes Dotctrl to create a git repository within the Dotctrl repository.
dotctrl init --gitYou can also combine this flag with the --auto flag:
dotctrl init --auto --gitWith the base already created, it's time for you to PULL the elements to the
base of Dotctrl with the pull command.
Pull single element to the Dotctrl repository:
dotctrl pull --e .zprofileIf you want to do a massive pull, do:
dotctrl pullNote: This option is only possible if you pass the elements manually in the dotctrl.json file or have not cleaned the registry.
After pulling the element(s), create symlinks to them in their original locations:
dotctrl link --e .zprofileIf you want to perform a massive link, do:
dotctrl linkNote: This option is only possible if you pass the elements manually in the dotctrl.json file or have not cleaned the record.
Unlink the repository element with the source location:
dotctrl unlink --e .zprofileIf you want to unlink elements massively, do:
dotctrl unlinkNote: This option is only possible if you pass the elements manually in the dotctrl.json file or have not cleaned the record.
This command will take an element from the Dotctrl repository and restore it to its original location:
dotctrl restore --e .zprofileIf you want to perform a massive restore, do:
dotctrl restoreNote: By default, when restoring element(s) to their original location, Dotctrl does NOT remove the elements from the registry (
dotctrl.json). To clean, see --autoclean.
This command brings information from the repository, see below some of its subcommands:
Check to see if there are elements to link:
dotctrl repo --checkCheck the elements already imported into the Dotctrl repository.
dotctrl repo --lsWith the command below you can see some information from the Dotctrl
repository, such as the number of folders and files,
the absolute path of the repository and if the environment variable
DOTCTRL_PATH is active.
dotctrl repo --infoSearches for any element within the Dotctrl repository. To do this, use the command:
dotctrl find --name .zprofileNote: Enclose the element to be found with double quotes if it has spaces in the name.
This command will manipulate the Dotctrl configuration file, see below some of its subcommands.
Clean up the elements present in the Dotctrl configuration file. Any element that is present in the Dotctrl configuration file and does not EXIST in the repository will be eliminated from the configuration file.
Usually --autoclean is used after using the command to restore
elements.
dotctrl config --autocleanTake a peek at the Dotctrl configuration file from the terminal.
Allows you to edit the Dotctrl configuration file in the terminal itself using the command:
dotctrl config --open
Note: It defaults to the
vimeditor, if not, it will try to usenano,emacsormicro.
Use this flag to change the language of Dotctrl. Dotctrl currently supports 2 (two) languages, they are: American English and Brazilian Portuguese. When using the command below, it will show a list for you to choose which language you want to use. The change is instantaneous.
dotctrl config --lang
The --e or --element flag is responsible for handling a specific element of the Dotctrl repository.
This flag must receive an element without the absolute path, only the relative
one from $HOME.
Examples:
dotctrl pull --e .zprofiledotctrl link --e .zprofiledotctrl unlink --e .zprofiledotctrl restore --e .zprofile
If the element has spaces in the name, enclose it in double quotes. Example:
dotctrl pull --e "file legal.txt file"
The --f or --force flag literally forces the use of the command,
preventing something from preventing its completion. This option is present in
all commands that manipulate elements, these commands are: pull, link,
unlink and restore.
This is an example of a complete Dotctrl configuration file
(dotctrl.json) structure:
{
"dotctrl": {
"config": {
"editor": "vim",
"language": "pt_BR"
},
"elements": [
".zshrc",
".config/xfce4/terminal/terminalrc",
".config/Code/User",
"Images/Wedding"
]
}
}By default, Dotctrl works with multiple directories, which makes you need to use it in a certain directory you created for your elements.
If you want to use Dotctrl in any PATH, you need to create an environment
variable that Dotctrl makes available. This environment variable is
DOTCTRL_PATH.
You must enter the DOTCTRL_PATH variable in your operating system containing
the directory where your dotfiles will be. For example, in your .bashrc or
.zshrc file:
Linux:
export DOTCTRL_PATH="/home/.dotfiles"or
macOS:
export DOTCTRL_PATH="/Users/.dotfiles"NOTE: Remember, when creating this environment variable, you will not be able to create other repositories for Dotctrl.
If Dotctrl has new features, please update the command line below:
python3 -m pip install dotctrl -U --userFor more command information, use:
dotctrl [--help | -h]
Now that you have control of your elements, it's time to deploy them to a git service. This example below will show you how to deploy and clone on GitHub.
1 - Deploy:
A - Entering the root folder created by Dotctrl:
Linux:
cd /home/.dotfilesmacOS:
cd /Users/.dotfilesB - Creating git repository, commit and saving (push)
git remote add origin [email protected]:<YOUR USER>/dotfiles.git
git init
git add .
git commit -m "Update"
git push origin main2 - Clone:
You can also clone any directory of your choice, but we'll keep the example build directory above. Follow the steps:
Linux:
sudo mkdir -p /home/.dotfiles
sudo chmod -R 770 /home/.dotfiles
cd /home/.dotfiles
git clone [email protected]:<YOUR USER>/dotfiles.git .
dotctrl link --fmacOS:
sudo mkdir -p /Users/.dotfiles
sudo chmod -R 770 /Users/.dotfiles
cd /Users/.dotfiles
git clone [email protected]:<YOUR USER>/dotfiles.git .
dotctrl link --fClick on the image below to be redirected to the donation forms:
It is very important that you make a donation to motivate further development of Dotctrl. :)
The project is available as open source under the terms of the MIT License ©
See, AUTHORS.