| Name | dotfilesmgmt JSON |
| Version |
0.0.6
JSON |
| download |
| home_page | None |
| Summary | Using Python virtual env and providing GIT_DIR, GIT_WORK_TREE environment variable for Git to manage dotfiles. |
| upload_time | 2024-09-08 08:18:45 |
| maintainer | None |
| docs_url | None |
| author | Kangjie YU |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Using dotfilesmgmt to manager your dotfiles(configuration files) under your home directory
## Introduction
> **Note**: This package is only available in PowerShell on Windows and bash on Linux(or WSL) **now** 😂.
When we want to use git to manage the dotfiles in our home directory, we want the home directory to be treated as a git repo, but other times we don't want it to be treated as a repo by git.
Inspired by the article [Managing Dotfiles With Git](https://gpanders.com/blog/managing-dotfiles-with-git/) which written by one of the maintainer of [Neovim](https://neovim.io/), I write this piece of code of the similar mechanism to help we use Git to maintain dotfiles under home directory.
You can use it in PowerShell or Bash in current version, other shells have not been tested not yet.
## Installation and Configuration and Usage
* Install the `pipx` (reference: <https://pipx.pypa.io/stable/>)`
* Install this package by `pipx install dotfilesmgmt`. if you want to edit the source code to adjust this package's behavior, just run `pipx install --editable dotfilesmgmt`
* Create a bare repo named `.dotfiles.git` used by this package under the home directory by `git init --bare ~/.dotfiles.git`.
* If you use bash, please export your \$PS1 variable such as appending(adding) `export PS1` in your
`~/.bashrc` profile file.
* Run `d5mgmt` to enter the subprocess interactive shell which has `GIT_WORK_TREE` and `GIT_DIR` environment variable setting.
Now you are in here: 
The subprocess shell will have the **shell prompt** start with `(dotfilesmgmt)`string, then you
can:
* Use git to manager your dotfiles in the subprocess shell.
~~Best~~ My Practice:
* append the following two lines to your `.dotfiles.git/info/exclude` file at first:
```
# untrack all files under the home directory
*
# track the relative path of this file itself which relative to the
# GIT_WORK_TREE (i.e.: home dir in our context)
!/.dotfiles.git/info/exclude
```
See also: [Ignoring Files](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)
in ProGit chapter 2.2
* add the file named "exclude" to our `.dotfiles.git` repo by `git add -f exclude` and `git commit` it.
* an example of tracking another file under home dir:
```
# make ~/.condarc could be tracked (i.e.: not ignored by git)
# by appending the line contains "!/.condarc" to the file 'exclude'
echo "!/.condarc" >> ~/.dotfiles.git/info/exclude
# track the ~/.condarc
git add ~/.condarc
# update all tracked files (include the 'exclude' file itself)
git add -u
# create the snapshot
git commit
```
* Enter `exit`. Enter `exit` will exit the subprocess shell which has `GIT_WORK_TREE` and `GIT_DIR`
setting, exit the d5mgmt program and go back to the origin shell with no above two variables
modification before you run `d5mgmt`:
*Press `exit` to return to the shell before you run `d5mgmt`*
* **All done**✔️.
### What does this package do? | Feature Approach, and Usage
After [installing and configuring](#installation-and-configuration) this package, if you run the `d5mgmt` or `d5mgmt.exe` executable in a shell, this executable will start a **subprocess** — the new instance of the shell interpreter, and setting following two git-related environment variable to the subprocess: the `GIT_WORK_TREE` and the `GIT_DIR`. The `GIT_WORK_TREE` is set to path of home directory (i.e., `$env:USERPFOFILE` on Windows, `$HOME` on LInux) and the `GIT_DIR` is set to the path of `.dotfiles.git` **bare** git repo(see also: [What is a "bare repo"?](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository)) which under the home directory.
Then if we run `git rev-parse --is-inside-work-tree` in home directory, we can get the result: the "**true**" string is outputted to stdout which mentions that git recognizes we are in the work(ing) tree of the bare repo because of two above git-related environment variable. Thus, we can use git *normally* as what we use git in a "**not**" bare repo under the home directory to manage dotfiles.
After we have managed dotfiles under the home directory already, just exit the subprocess shell (e.g., enter `exit`) and return to the shell which doesn't setting`GIT_DIR` and `GIT_WORK_TREE`.
### If you use oh-my-posh and meet its "[git segment](https://ohmyposh.dev/docs/segments/scm/git)" display issue after running `d5mgmt` in PowerShell, how to solve it?
#### How to solve it? - two steps
1. Install **posh-git** module and `Import-Module posh-git` in your pwsh **\$profile**. (see also: [about_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.4))
2. Insert the following JavaScript object before or after the **git-segment**'s object in the `"segments": []` list in the **oh-my-posh theme** which you used:
```json
{
"type": "text",
"style": "plain",
"template": "{{if .Segments.Git}}{{else}}{{if .Env.POSH_GIT_STRING}}git:{{ .Env.POSH_GIT_STRING }}{{end}}{{end}}",
"properties": {
}
},
```
**Explain the "template" property above**: using the [cross-segment-template-properties](https://ohmyposh.dev/docs/configuration/templates#cross-segment-template-properties) `.Segments.Git` in this ["text" segment](https://ohmyposh.dev/docs/segments/system/text)'s template". If the `.Segments.Git` is empty and the `.Env.POSH_GIT_STRING` (the `$env:POSH_GIT_STRING` itself) is not empty, show the `$env:POSH_GIT_STRING` in the shell prompt.
#### The issue which we can solve(bypass) by above two steps.
In PowerShell, if we set the `$env:GIT_DIR` and `$env:GIT_WORK_TREE`, [**posh-git**](https://github.com/dahlbyk/posh-git) module can recognize which is the bare repo and which is the work tree of the bare repo but oh-my-posh's [**git segment**](https://ohmyposh.dev/docs/segments/scm/git) can't.
Here is the example showing the different display result between **posh-git** and **oh-my-posh** (support the posh-git and oh-my-posh already installed and the `$env:GIT_DIR` and `$env:GIT_WORK_TREE` are not set at the beginning):
##### §About **posh-git**:
1. Run`pwsh.exe -NoProfile` to start a PowerShell session without any PowerShell **`$PROFILE`** (see also: [about_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.4))
2. Enter `Import-Module posh-git` to import the module.
3. `cd ~/.dotfiles.git` to into the **bare repo**, the value of **posh-git**'s **git string** (value of `$env:POSH_GIT_STRING`) is automatically appended to the shell prompt.
4. Now, outside the bare repo (e.g.: `cd ~`), the `$env:POSH_GIT_STRING` be **empty** , then:
1. set `$env:GIT_DIR` to the path of the bare repo (e.g.: `$env:GIT_DIR="C:\Users\User\.dotfiles.git"`)
2. set `$env:GIT_WORK_TREE` to our home directory (e.g.: `$env:GIT_WORK_TREE="C:\Users\User"`)
we can see the `$env:POSH_GIT_STRING` appends to the shell string.
##### §About **oh-my-posh**:
1. Running `pwsh.exe`. Running it without options and without arguments in above step 1 will load **\$Profile** file automatically. If we have `oh-my-posh init pwsh --config "path\to\oh-my-posh\theme.json" | Invoke-Expression` in **$PROFILE**, The **oh-my-posh** will use **git segment** to show the git prompt string,
2. Same as above §[About posh-git](#about-posh-git) step 2.
3. `cd ~/.dotfiles.git` as above step 3, but now the git prompt is display by **git segment**.
4. Same as above step 4, after we set those two variable, the **git segment** is <mark>missing in shell prompt</mark> although we can also get the value of`$env:POSH_GIT_STRING`provided by **posh-git** in stdout by run `$env:POSH_GIT_STRING`.
Solution see [How to solve it? - two steps](#how-to-solve-it---two-steps) above.
Raw data
{
"_id": null,
"home_page": null,
"name": "dotfilesmgmt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Kangjie YU",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/26/af/75f5ee4bba2bcf6e866a0c8ea536d7fe590f97ecd76c79aa19dd623ac91d/dotfilesmgmt-0.0.6.tar.gz",
"platform": null,
"description": "# Using dotfilesmgmt to manager your dotfiles(configuration files) under your home directory\n\n## Introduction\n\n> **Note**: This package is only available in PowerShell on Windows and bash on Linux(or WSL) **now** \ud83d\ude02.\n\nWhen we want to use git to manage the dotfiles in our home directory, we want the home directory to be treated as a git repo, but other times we don't want it to be treated as a repo by git.\n\nInspired by the article [Managing Dotfiles With Git](https://gpanders.com/blog/managing-dotfiles-with-git/) which written by one of the maintainer of [Neovim](https://neovim.io/), I write this piece of code of the similar mechanism to help we use Git to maintain dotfiles under home directory.\n\nYou can use it in PowerShell or Bash in current version, other shells have not been tested not yet.\n\n## Installation and Configuration and Usage\n\n* Install the `pipx` (reference: <https://pipx.pypa.io/stable/>)`\n* Install this package by `pipx install dotfilesmgmt`. if you want to edit the source code to adjust this package's behavior, just run `pipx install --editable dotfilesmgmt`\n* Create a bare repo named `.dotfiles.git` used by this package under the home directory by `git init --bare ~/.dotfiles.git`.\n* If you use bash, please export your \\$PS1 variable such as appending(adding) `export PS1` in your\n`~/.bashrc` profile file.\n* Run `d5mgmt` to enter the subprocess interactive shell which has `GIT_WORK_TREE` and `GIT_DIR` environment variable setting.\n Now you are in here: \n\nThe subprocess shell will have the **shell prompt** start with `(dotfilesmgmt)`string, then you\ncan:\n\n* Use git to manager your dotfiles in the subprocess shell. \n ~~Best~~ My Practice: \n * append the following two lines to your `.dotfiles.git/info/exclude` file at first: \n \t```\n\t# untrack all files under the home directory\n\t*\n\t# track the relative path of this file itself which relative to the\n\t# GIT_WORK_TREE (i.e.: home dir in our context)\n\t!/.dotfiles.git/info/exclude\n\t```\n\tSee also: [Ignoring Files](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)\n\tin ProGit chapter 2.2\n * add the file named \"exclude\" to our `.dotfiles.git` repo by `git add -f exclude` and `git commit` it. \n * an example of tracking another file under home dir:\n\t```\n\t# make ~/.condarc could be tracked (i.e.: not ignored by git)\n\t# by appending the line contains \"!/.condarc\" to the file 'exclude'\n\techo \"!/.condarc\" >> ~/.dotfiles.git/info/exclude\n\t# track the ~/.condarc\n\tgit add ~/.condarc\n\t# update all tracked files (include the 'exclude' file itself)\n\tgit add -u\n\t# create the snapshot\n\tgit commit\n\t```\n* Enter `exit`. Enter `exit` will exit the subprocess shell which has `GIT_WORK_TREE` and `GIT_DIR`\n setting, exit the d5mgmt program and go back to the origin shell with no above two variables\n modification before you run `d5mgmt`: \n  \n *Press `exit` to return to the shell before you run `d5mgmt`*\n* **All done**\u2714\ufe0f.\n\n### What does this package do? | Feature Approach, and Usage\n\nAfter [installing and configuring](#installation-and-configuration) this package, if you run the `d5mgmt` or `d5mgmt.exe` executable in a shell, this executable will start a **subprocess** \u2014 the new instance of the shell interpreter, and setting following two git-related environment variable to the subprocess: the `GIT_WORK_TREE` and the `GIT_DIR`. The `GIT_WORK_TREE` is set to path of home directory (i.e., `$env:USERPFOFILE` on Windows, `$HOME` on LInux) and the `GIT_DIR` is set to the path of `.dotfiles.git` **bare** git repo(see also: [What is a \"bare repo\"?](https://git-scm.com/docs/gitglossary#Documentation/gitglossary.txt-aiddefbarerepositoryabarerepository)) which under the home directory.\n\nThen if we run `git rev-parse --is-inside-work-tree` in home directory, we can get the result: the \"**true**\" string is outputted to stdout which mentions that git recognizes we are in the work(ing) tree of the bare repo because of two above git-related environment variable. Thus, we can use git *normally* as what we use git in a \"**not**\" bare repo under the home directory to manage dotfiles.\n\nAfter we have managed dotfiles under the home directory already, just exit the subprocess shell (e.g., enter `exit`) and return to the shell which doesn't setting`GIT_DIR` and `GIT_WORK_TREE`.\n\n### If you use oh-my-posh and meet its \"[git segment](https://ohmyposh.dev/docs/segments/scm/git)\" display issue after running `d5mgmt` in PowerShell, how to solve it?\n\n#### How to solve it? - two steps\n\n1. Install **posh-git** module and `Import-Module posh-git` in your pwsh **\\$profile**. (see also: [about_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.4))\n\n2. Insert the following JavaScript object before or after the **git-segment**'s object in the `\"segments\": []` list in the **oh-my-posh theme** which you used:\n\n```json\n{\n\t\"type\": \"text\",\n\t\"style\": \"plain\",\n\t\"template\": \"{{if .Segments.Git}}{{else}}{{if .Env.POSH_GIT_STRING}}git:{{ .Env.POSH_GIT_STRING }}{{end}}{{end}}\",\n\t\"properties\": {\n\t}\n},\n```\n\n**Explain the \"template\" property above**: using the [cross-segment-template-properties](https://ohmyposh.dev/docs/configuration/templates#cross-segment-template-properties) `.Segments.Git` in this [\"text\" segment](https://ohmyposh.dev/docs/segments/system/text)'s template\". If the `.Segments.Git` is empty and the `.Env.POSH_GIT_STRING` (the `$env:POSH_GIT_STRING` itself) is not empty, show the `$env:POSH_GIT_STRING` in the shell prompt.\n\n#### The issue which we can solve(bypass) by above two steps.\n\nIn PowerShell, if we set the `$env:GIT_DIR` and `$env:GIT_WORK_TREE`, [**posh-git**](https://github.com/dahlbyk/posh-git) module can recognize which is the bare repo and which is the work tree of the bare repo but oh-my-posh's [**git segment**](https://ohmyposh.dev/docs/segments/scm/git) can't. \n\nHere is the example showing the different display result between **posh-git** and **oh-my-posh** (support the posh-git and oh-my-posh already installed and the `$env:GIT_DIR` and `$env:GIT_WORK_TREE` are not set at the beginning):\n\n##### \u00a7About **posh-git**:\n\n1. Run`pwsh.exe -NoProfile` to start a PowerShell session without any PowerShell **`$PROFILE`** (see also: [about_Profiles](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_profiles?view=powershell-7.4))\n\n2. Enter `Import-Module posh-git` to import the module.\n\n3. `cd ~/.dotfiles.git` to into the **bare repo**, the value of **posh-git**'s **git string** (value of `$env:POSH_GIT_STRING`) is automatically appended to the shell prompt.\n\n4. Now, outside the bare repo (e.g.: `cd ~`), the `$env:POSH_GIT_STRING` be **empty** , then:\n\n 1. set `$env:GIT_DIR` to the path of the bare repo (e.g.: `$env:GIT_DIR=\"C:\\Users\\User\\.dotfiles.git\"`)\n\n 2. set `$env:GIT_WORK_TREE` to our home directory (e.g.: `$env:GIT_WORK_TREE=\"C:\\Users\\User\"`)\n\n we can see the `$env:POSH_GIT_STRING` appends to the shell string.\n\n##### \u00a7About **oh-my-posh**:\n\n1. Running `pwsh.exe`. Running it without options and without arguments in above step 1 will load **\\$Profile** file automatically. If we have `oh-my-posh init pwsh --config \"path\\to\\oh-my-posh\\theme.json\" | Invoke-Expression` in **$PROFILE**, The **oh-my-posh** will use **git segment** to show the git prompt string,\n\n2. Same as above \u00a7[About posh-git](#about-posh-git) step 2.\n3. `cd ~/.dotfiles.git` as above step 3, but now the git prompt is display by **git segment**.\n4. Same as above step 4, after we set those two variable, the **git segment** is <mark>missing in shell prompt</mark> although we can also get the value of`$env:POSH_GIT_STRING`provided by **posh-git** in stdout by run `$env:POSH_GIT_STRING`.\n\nSolution see [How to solve it? - two steps](#how-to-solve-it---two-steps) above.\n",
"bugtrack_url": null,
"license": null,
"summary": "Using Python virtual env and providing GIT_DIR, GIT_WORK_TREE environment variable for Git to manage dotfiles.",
"version": "0.0.6",
"project_urls": {
"Homepage": "https://github.com/YuKangjie/dotfilesmgmt",
"Issues": "https://github.com/YuKangjie/dotfilesmgmt/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "04f84b19fd8a348b4fa425551215b151b70851db0477c7c1ae098e26f604cb6f",
"md5": "a8c2228c01e44c81e61dafc0a034ed52",
"sha256": "ebf9d627ebee815a1fe2d0524bcc4cbd27b32762ec4e17a154cf2fc2b083458e"
},
"downloads": -1,
"filename": "dotfilesmgmt-0.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8c2228c01e44c81e61dafc0a034ed52",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 8161,
"upload_time": "2024-09-08T08:18:43",
"upload_time_iso_8601": "2024-09-08T08:18:43.089491Z",
"url": "https://files.pythonhosted.org/packages/04/f8/4b19fd8a348b4fa425551215b151b70851db0477c7c1ae098e26f604cb6f/dotfilesmgmt-0.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "26af75f5ee4bba2bcf6e866a0c8ea536d7fe590f97ecd76c79aa19dd623ac91d",
"md5": "531b2d03499b620e6cd6a6d01c6c7d02",
"sha256": "eb5cc6256ed208accc23f531906f7a9f13aff0ae130d85089330ed585c7611e3"
},
"downloads": -1,
"filename": "dotfilesmgmt-0.0.6.tar.gz",
"has_sig": false,
"md5_digest": "531b2d03499b620e6cd6a6d01c6c7d02",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 62254,
"upload_time": "2024-09-08T08:18:45",
"upload_time_iso_8601": "2024-09-08T08:18:45.099754Z",
"url": "https://files.pythonhosted.org/packages/26/af/75f5ee4bba2bcf6e866a0c8ea536d7fe590f97ecd76c79aa19dd623ac91d/dotfilesmgmt-0.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-08 08:18:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "YuKangjie",
"github_project": "dotfilesmgmt",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "dotfilesmgmt"
}
