I thought that mani sync would also synchronize all remotes, but it only clones them... if you want to fetch or similar, then you have to set up a task.

Example:

tasks:
  git-status:
    desc: Show working tree status
    cmd: git status

Then to execute:

mani run git-status --all

(you have to specify tags or --all or similar... it won't just run automatically against everything)

See ChatGPT chat for more context.

[dotfiles are] user-specific application configuration is traditionally stored in so called dotfiles (files whose filename starts with a dot).

dotfiles Overview

When asked by coworkers, I usually describe them as user config files commonly used in Linux related systems (e.g. Ubuntu, MacOS). On Linux or Mac, your dotfiles live under your $HOME or ~ directory (which can vary by OS). If you're coming from a Windows background, you may still see dotfiles for your Linux-like tools, though. For example, here are a couple of Windows tools that use dotfiles:

• Git uses the %USERPROFILE%\.gitconfig (e.g. C:\Users\David\.gitconfig)
• Vim uses the %USERPROFILE%\.vimrc (e.g. C:\Users\David\.vimrc)

So in this case, %USERPROFILE% corresponds to ~, which is what PowerShell uses for its HOME, too. It is probably more common for Windows-specific tools to use the various App Profile directories (%USERPROFILE%\AppData).

Some of the usefulness of dotfiles is storing the configuration in source control, because then you can easily port your customizations and configuration over to other machines. I have my dotfiles set up so that it is cross platform and can be used across Mac, Linux and even Windows.

My dotfiles setup

My dotfiles repo is up at https://github.com/drmohundro/dotfiles. It has my user configuration history from the last fifteen years (see my first commit). At that time, it looks like I was using Vim, playing with Emacs, using Ack, and still storing my PowerShell files there (though I have since moved them to their own repository).

Today, 500+ commits later, I've got even more tool configuration. I've still got Vim, but I also added Neovim, Hammerspoon, both Kitty and Wezterm, both oh-my-posh and starship, multiple shell configs (i.e. fish, zsh and bash), and more.

The best part? All it takes for me to set up a new environment is a simple git clone and then an install script.

So first off, why a separate directory plus install script verses just tracking everything directly in your home directory? Some people do prefer to just run git init in their home directory. Personally, I don't like that because I don't want to mess with ignoring tools I don't want to track and the other directories that live there (like Documents, Photos, etc.).

Also, what's the deal with the files not having the . in the name? Is it even dotfiles at this point? I actually found this approach originally from Ryan Bates dotfiles.

One benefit of this approach is that the files aren't hidden (files with . at the beginning are hidden on Mac and Linux). You open your directory, they're right there.

Another benefit is that there is a clear distinction between repository config files and home user config files. What I mean is, I can have a .gitignore or an .editorconfig _for the dotfiles repository, but it isn't for the entire machine like the rest of the dotfiles.

My Install Script

My installation script is up at https://github.com/drmohundro/dotfiles/blob/main/install.ps1.

So... why use a PowerShell install script? Especially given that we've already noted that dotfiles are mostly for Linux and Mac?

That's a great question.

So at one point, I used almost the exact same Rakefile that Ryan Bates did it was removed here. In fact, I used almost his identical script until 2020, but then I added a PowerShell script for installation instead.

Why change? One ironic reason is that I wanted an easy cross platform approach. Ruby (and Rake) will work on Windows, but it has historically been pretty painful. And PowerShell Core now runs on Windows, Mac and Linux. Another simpler reason is that I know and like PowerShell.

The final reason is that, as part of my cross platform setup, I wanted to override where some of the directories would be dropped by OS. Let me explain that more.

First off, the script by default just loops (almost) every file, does some logic to determine the target path, and then creates a symbolic link (or Windows junction for directories on Windows). This means I can edit my files in my home or dotfiles directory and the changes are immediately live.

Below is the code for creating the symbolic link (or junction):

    if ($whatIf) {
        log "Linking $($map.Link) to $($map.Target)"
    }
    else {
        if ((Get-Item $map.Target) -is [System.IO.DirectoryInfo] -and $IsWindows) {
            New-Item -Path $_.Link -ItemType Junction -Value $_.Target
        }
        else {
            New-Item -Path $_.Link -ItemType SymbolicLink -Value $_.Target
        }
    }

Second, I have an overrides.json configuration file at https://github.com/drmohundro/dotfiles/blob/main/overrides.json. This lets me mix things up by OS. For example, on both Mac and Linux, neovim is configured to drop to ~/.config/nvim, but on Windows it goes to %LOCALAPPDATA%/nvim/init.vim. Most tools don't have to have any setup, but I like that I can customize when needed.

Finally, I added a -whatIf switch that doesn't actually install or change anything, but just reports what would have happened.

Alternative Approaches for Managing dotfiles

If you've researched dotfiles at all, you may have come across other approaches like chezmoi or stow. There is a great list of tools at https://dotfiles.github.io/utilities/ (along with other resources, too).

If one of those tools works for you, that's totally fine! I find my slightly unique setup works for me, though. And that highlights one of the things I like about dotfiles in general... they reflect the personality of the author.

Finding Inspiration in Other dotfiles

The reason I got into dotfiles in the first place was reading up on customizing vim. I'd find blog posts talking about various vim setups and the posts would link to various dotfile repositories. These are great ways to learn the ins and outs of various tools, configurations and more.

A great way to see what's out there is a GitHub search for "dotfiles".

Past that, including the tools you're interested in configuring along with "dotfiles" can go even farther (e.g. fish, zsh, git, nvim, vim, etc.). If you know what the name of the specific dotfile would be, that's even better:

• config.fish for fish
• .zshrc for zsh
• .gitconfig for git
• init.vim or init.lua for neovim
• .vimrc for vim

Additional Tips

The main thing I'd suggest for anyone that doesn't already manage their dotfiles is to start small. Think about the sorts of setup you do on new machines (or if you have to SSH to other servers)... is it just your .gitconfig with some git aliases? Or is it just your shell with aliases? Don't try to get fancy with anything. Just start keeping track of those in source.

I find it interesting to look at other people's dotfiles... you can learn a lot about someone:

• If someone's Vim set up is less than 20 lines long, they're likely a minimalist
• If someone's history for their dotfiles only 5-10 commits, they probably don't play with their config much (and they tend to be content with their tools)
• If someone has 500+ commits (cough like me cough), then they may spend a weekend playing with a new configuration just for fun.

Finally, it is a great way to learn about a new config option or tool. I'll sometimes find a repo with a setup or alias I like, but then I'll look at the root and see a file I don't recognize... I think I learned about Neovim's Lua configuration from dotfiles before I found it in the documentation.

If you have any additional dotfile tips, feel free to let me know!

We've been very happy with Mercurial since that time. Other than the initial ramp up time for the team to learn the intricacies of DVCSs, we honestly haven't had any major issues. What might have taken half a day to work through now takes minutes.

However, if you've noticed the title, we have now migrated to Git. I'm not going to spend much time on the "why" except to say that we were standardizing on a common VCS tool across the enterprise and that the current plan is to use a commercial Git offering.

Caveats about our usage of Mercurial

Before I go through the options that we looked at, I do want to mention some points about how we were using Mercurial.

First off, we didn't use the standard "First Last {'email@email.com'}" format in our HG config. Don't ask why, because I don't remember why. Short of rewriting history, it was something we were stuck with.

Second, there were three years of history from a team of developers. In other words, the repository was quite large.

hg-fast-export

The first option that I researched was hg-fast-export (via fast-export). It was nice in that you could pass in an authors mapping file to convert from old name formats to new name formats.

The basic steps to use it are:

mkdir my-new-repo
cd my-new-repo
git init
hg-fast-export -r ../path/to/hg/repo -A ../authors.txt

It actually worked fine for our smaller repositories. It did however fail when I tried to convert our main repository. My guess is that we had a branch somewhere that had multiple heads or something. I couldn't find the revision it failed on which suggests to me that a bad commit had been stripped or something. Not ideal, but something that we had to deal with.

The other issue is that it took hours to convert a large repository. This wouldn't be a big deal in and of itself except that I couldn't get the conversion to work on our primary repo.

hg-git

Given that hg-fast-export wasn't working well, I then looked into hg-git. hg-git was promising in that I thought I'd be able to set up a git remote and push to it from the existing hg repository; however, I had issues with that.

I was able to get the hg gexport command working, though. It creates a git directory under your .hg directory (unless you configure the intree option). This process worked quite well, but it took eight hours to complete.

Once the conversion happened, I could copy the git directory out, rename it to .git and I had my local git repository (note that I did have to set the git core.bare option to false).

At this point, I had gone from a multiple hour long process that didn't work to a multiple hour long process that did work. Neither was ideal, though, because I had to tell the team to stop pushing changes while I was converting the repository. That, or re-run the export again.

git-remote-hg

Given that during my one successful run of hg gexport, I had missed some commits, I decided to do a little more research, which led me to the git-remote-hg script. This script will actually be shipping with git at some point, which gives it some credibility in my book. It works by letting you clone from HG via a URL, like git clone hg::/path/to/your/repo. Note the leading hg::. The other nice thing is that, since it is a remote in git, you can continue to pull updates down.

My favorite thing about git-remote-hg, though, is its speed. It could clone our entire repository in under 15 minutes.

To get it to work, you just have to drop it in your PATH somewhere. I tried to get it to work on Windows, but was unsuccessful. I decided to bail and use it on OSX because 1) OSX was available and 2) I had read a lot of successes online from people who were using it on OSX. I did have to tweak the first line of the script to point to my homebrew install of Python, but other than that, it just worked.

The one issue with git-remote-hg I had is that I couldn't find an effective means of modifying authors. After the conversion, I could run git filter-branch --env-filter scripts to modify the git authors (see the GitHub "changing author info" link). The problem with the these scripts is that, as far as I could tell, they only work on one author at a time and they took about 45 minutes to complete.

Final solution

It was at this time that I remembered Scott Hanselman's words that "the Internet is not a black box". In other words, the git-remote-hg script also is not a black box - it's just a Python script. Perhaps I could add my own author mapping code and shorten the feedback loop from hours to minutes.

Basically, I changed the code in the method fixup_user() to have the following code (with censored users and emails):

found_user = '%s <%s>' % (name, mail)

user_mapping = {
    "Bob <unknown>": "Bob Dev <bob.dev@fakeemail.com>",
    "John <unknown>": "John Doe <john.doe@fakeemail.com>",
    "Jane <unknown>": "Jane Smith <jane.smith@fakeemail.com>",
}

try:
    mapped_author = user_mapping[found_user]
    found_user = mapped_author
except KeyError:
    warn("Couldn't find user mapping for %s" % found_user)

return found_user

Finally, success! The best part was that I had a repeatable process that ran quickly! Once that was complete, I was able to successfully push the repository to the new remote that I had set up.

If you're like most .NET developers, chances are quite high that you're developing on Windows. In case you're unaware, git was originally written to manage the Linux source code. What this means is that it has a very different philosophy than your standard Windows application. For one, it is primarily used from the command line. And yes, I realize that a plethora of various GUI tools for git exist. The only one I personally use is gitk, though, and only then to get a high level view of the repository. The rest of the time, I use it entirely from the command line (Powershell actually). I wanted to share some tips on using git in Windows and making the experience better. (note that this isn't a "git tutorial," it's a "setting git up on Windows tutorial.")

Install MSysgit

First off, you have two options for running git in Windows - msysgit or cygwin. I've used both, but I currently prefer using msysgit, mainly because when I'm on Windows, I want to use Powershell. Most posts you'll read from Windows users using git actually use Git Bash that ships with msysgit, though. I've used this option as well, but as I said, I like my Powershell. If you want to use git from any command prompt (including cmd, git bash, or powershell), you'll want to choose the option to add the git directory to your path when you install msysgit. (you might have to restart before the PATH changes are effective)

After the install, you can verify things are set up correctly by pulling up powershell and typing get-command git. If everything was installed correctly, you should see something like this:

You can now type git --version to verify that the install worked. Mine outputs "git version 1.6.5.1.msysgit.1".

Use Console2

The next step is one of the most important ones in my opinion. Don't use the default cmd.exe. Use a better one. I recommend Console2. It's a tabbed console host for windows. You can use it to host the standard cmd prompt, powershell, cygwin, git bash, etc. It has much better font and color support, too. None of this adding fonts to the registry so that cmd.exe can use Consolas mess. Here's what mine looks like:

I've customized my colors so that the black is more of a dark gray and some of the other colors aren't quite as bold. I've changed my font to Consolas, I've got the menu, toolbar and status bar hidden, I have copy on cursor select checked, and more. Some people don't care about aesthetics when coding or using the command prompt, but I do.

Enable color with git

Speaking of aesthetics, I cringe every time I see someone run git status and see no color. I don't think I knew how big of a difference existed until I ran git on an Ubuntu VM where color support is enabled out of the box. Here, I'll just show you a couple screenshots for comparison.

Without color...

With color!

Now, if you've used git, you may be aware of the git config option (or see ~/.gitconfig) to turn color on. I actually have mine set to auto. This means that git tries to determine, based on your terminal, if it thinks you can handle color or not. It doesn't think Windows can handle color very well, so auto on Windows means no color. So, if I'm not using the global color option, what am I doing to tell git to use color anyway? I'm using an environment variable tweak that I learned about via one of the msysgit issues). Here's the line from my powershell profile:

$env:TERM = 'cygwin'
$env:LESS = 'FRSX'

This line basically lies about the running terminal - "hi git, my terminal isn't actually powershell or cmd.exe or console2, it's actually cygwin." The second line provides arguments to less (the default git pager) on how to render its output.

Here's how this changes things...

Before:

After!

It's pretty clear now what's changed.

What's could still improve?

The only thing I'm currently missing from git when using it via Powershell now is the tab completion. Git provides a bash_completion script so that you can tab complete all of the various commands, the branch names when switching between branches, the various file names when adding or removing, etc. I've started to create my own version of tab completion when using Powershell by tweaking PowerTab (Gaurav Sharma started the initial research to do this... check out his post at http://techblogging.wordpress.com/2008/10/13/context-sensitive-auto-completion-using-powershell-powertab-and-git/) but it isn't yet nearly as powerful as what the bash_completion script provides when using a bash terminal. I'm hopeful that future versions of Powershell will provide a better (easier?) way to hook tab completion up, particularly for utilities that aren't Powershell-aware. The TabExpansion function is a little too global for my taste - unless I'm missing something, if you want to add to the tab completion functionality that already exists, you pretty much have to re-implement all of the tab completion functionality.

That's pretty much it. Don't be afraid of the command line and don't be afraid of command line tools.

EDIT: added the $env:LESS setting - just setting TERM doesn't seem to work in all cases.