Development Environment Helpers: git

This repo contains opinionated recommendations and suggestions as to the tools that many frontend developers (especially beginners) will find useful.

If you are a beginner frontend developer you may also find dev-env-frontend recommendations useful.

Table of Contents

• Intro
• Basic setup
  • Credentials manager
• Friendly git editor
  • What might go wrong?
• Git Helpers
  • CLI Enhancements
  • Git Aliases
  • Git Flow
    • Basic flow
    • Git Town
• More resources on tweaking git
• Advanced
  • Subrepo
• IDE minimal tweak
  • .editorconfig
• Issues?
• Contributors

Intro

This repo contains scripts that make git users' and project maintainers' life easier.

All scripts are optional. It is recommended that you look into the script of your choice before using it. Some scripts require you to patch e.g. file path before they can be efficiently invoked.

Some tools/scripts are specific to Windows OS (as denoted). Under Windows scripts are intended to get launched under e.g. Git Bash that comes bundled with git distribution. It would be available from file explorer context menu.

In terminal navigate to this project directory and execute chmod u=rwx *.sh to make shell scripts executable.

Remember to precede script with explicit path, e.g. ./script.sh

Basic setup

Get registered with github.com.

Install git.

Notes for Windows users

When prompted to choose an editor it is recommended that you opt for Notepad++ (a GUI enabled editor) or Nano (non-GUI, yet friendlier to beginners than vim). When prompted for extra options enable file system caching.

Open Terminal (Git Bash under Windows). The most of the instructions below are to be completed in Terminal.

A note for Windows users (click to expand)

Did you know you can open git bash from File Explorer? Locate your project (or just e.g. any directory in your file system) in File Explorer, right click within explorer window to open context menu and select "Git Bash Here" option.

Bash will get opened in context of your project.

All OS

Execute following commands to have your git identity configured. Replace "John Doe" with your real name (obey quotes) and [email protected] with the email GitHub suggests in your settings https://github.com/settings/emails to protect your real email address from parsing.

git config --global user.name "John Doe"
git config --global user.email [email protected]

Note! Copy-paste + edit are your best friends most of the time.

Navigate to the location you are going to have your development projects in. Your home directory is a good point to start at. You can get to your home directory by executing cd ~/ command in Terminal.

Next execute the following commands one-by-one to have all required files from this repository on your machine:

git clone https://github.com/OleksiyRudenko/dev-env-git.git
cd dev-env-git

Execute chmod u=rwx *.sh to make shell scripts executable.

You may close Terminal eventually. You can get back to this project at any time by executing the following command in terminal to catch up:

cd ~/dev-env-git

A recommendation on projects organization

Consider using the projects directory structure that reflects your accounts on potentially multiple repo hosting platforms, both your personal and under various organizations you may be a part to.

/dev
 |-- kottans.gh  # projects that are hosted under Kottans org on GitHub
 |-- or.gh       # projects that are hosted under Oleksiy Rudenko's acc on GitHub
 \-- or.gl       # projects that are hosted under Oleksiy Rudenko's acc on GitLab

This way you will also be able to fine tune git per directory tree. (Paths below are in Windows notation).

# ~/.gitconfig
[user]
    name = "John Doe"

[includeIf "gitdir:C:/dev/or.gh/**"]
    path = ~/.gitconfig.dev.or.gh.gitconfig

[includeIf "gitdir:C:/dev/or.gl/**"]
    path = ~/.gitconfig.dev.or.gl.gitconfig

# ~/.gitconfig.dev.or.gh.gitconfig
[user]
    email = 999999[email protected]"

# ~/.gitconfig.dev.or.gl.gitconfig
[user]
    email = [email protected]"

Credentials manager

Credential manager helps to avoid authorization phase at every operation on remote repo with git.

Windows: Install Git Credential Manager for Windows. For downloads unfold and check Assets subsection below latest release Change Log.

MacOS: OSX keychain store is used by default, no need to install anything. Just tell Git to use the KeyChain to store your credentials:

git config --global credential.helper osxkeychain

Linux Mint/Ubuntu

Execute ./credential-manager-linux.sh in Terminal:

If any command fails try googling the error message to fix the issue.

Alternatively, for Linux you may try Git Credential Manager from Microsoft.

Success criteria: when Credential Manager is installed properly git will ask for access credentials only once per each remote repos storage (e.g. GitHub), normally on first attempt to push your local repo to the remote.

If under Windows you are getting prompted for credentials repeatedly or presented with an error message

fatal: HttpRequestException encountered.
   An error occurred while sending the request.
fatal: HttpRequestException encountered.
   An error occurred while sending the request.
Username for 'https://github.com':

try the following command: git config --global credential.modalPrompt true. Check official docs for the fixes for other possible issues you may face. Keep this project among your bookmarks just for the case you face the authentication issue at some later time.

Friendly git editor

Many won't find vim or vi (that are used by default by git) friendly enough.

Alternatives are:

• GNU emacs
• Sublime Text
• Visual Studio Code
• Notepad++ (Windows only)
• nano (Linux/MacOS only)

NB: Windows Notepad.exe is not a recommended option as it doesn't support Linux linefeed.

Windows: if you're opted for Notepad++ or Nano when when installed git and you're happy with your choice, you may skip this section completely.

You may opt for a different editor of your choice. There is a couple of basic requirements it should meet:

• support Linux style linefeed
• CLI friendly (normally offers an option like --wait to correctly handle files)
• be lightweight enough to start quickly

Google for "your-editor-name as a git editor" to check how to use your favourite editor with git.

Install an editor of your choice (git-editor-linux.sh contains instructions to install nano or emacs).

Emacs under Windows: unpack distribution archive into C:/Program Files/emacs

MacOS: You may need to move downloaded installations to Applications.

Some editors come pre-bundled with OS, so try launching the editor of your choice from Terminal to know if you need installing it first.

Open corresponding git-editor-<platform>.sh to edit. <platform> is your OS: linux, macos, or windows.

Uncomment (remove leading # ) section that corresponds to your editor of choice and edit the path to the editor executable as the pre-defined may not match actual installation path.

Linux CLI commands command -v <executable_name> and which <executable_name> may help you find proper path.

Then launch the script with ./git-editor-<platform>.sh.

If the editor of your choice opens and you see something like

[user]
	name = John Doe
	email = [email protected]
	username = JohnDoe
[core]
	editor = 'D:/Program Files (x86)/Notepad++/notepad++.exe' -multiInst -notabbar -nosession -noPlugin ''
	pager = cat
[credential]
	helper = wincred

then you have succeeded. Just close the editor.

What might go wrong?

You can see the file above but the editor is not the one you expected.

You might not have all lines relevant to your editor in ./git-editor-<platform>.sh uncommented. So, the default editor didn't change.

1. Quit the editor.
   • If editor shows commands in a toolbar then press a relevant hot-key (normally ^X or ^Q)
   • If editor offers GUI then option to quit is located under File menu
   • You may find yourself in vim or vi. Press ESC, type :q! and hit Return key
2. Uncomment relevant commands in ./git-editor-<platform>.sh by removing leading # .
3. Launch ./git-editor-<platform>.sh

Editor didn't start. Some error reported

The path to the editor in ./git-editor-<platform>.sh is not correct.

1. Fix path to your editor in ./git-editor-<platform>.sh. Try finding proper path to your editor. Optionally consult google for a proper path to the editor of your choice as described in this section above.
2. Launch ./git-editor-<platform>.sh

If you do not succeed either then try setting different editor. Do not forget to comment back failing commands in ./git-editor-<platform>.sh before uncommenting commands for a different editor. Or yell for help in your student community.

Git Helpers

CLI Enhancements

Make your terminal shell prompt informative. Executing ./cli-tune.sh will copy .bash_profile, git-completion.bash and git-prompt.sh to your $HOME.

The above improves CLI by e.g. adding info about current git branch to the shell prompt and adding auto-completion feature to git commands (branch names, commands per se, etc.).

It may happen that either of file copying operation fails. Most likely either of files already exists at target directory (~/). There are chances you have already tuned your CLI for git any time before. As for the .bash_profile you may already have one, then just update ~/.bash_profile with contents of this project's .bash_profile.

You'll need to close and re-open Git Bash before any changes take effect.

Credits: Udacity

Learn more about Customizing Linux/Mac terminal prompt

Git Aliases

Executing ./git-helpers.sh will:

• add global .gitignore to ignore most common file patterns

• add a collection of aliases/shorthands

• Study git-helper.sh, try commands assigned to aliases on some of your repos to see what those do. Some of aliases:

More on global .gitignore: Global .gitignore decreases a risk of tracking of the most common files to be ignored (IDE settings, temporary files, directories for app builds etc). Global .gitignore works even when the project doesn't contain its own .gitignore. You may add more rules or remove some by editing ~/.gitignore.

More on aliases: Adding those is not harmful, using can be. Study git-helper.sh, try commands assigned to aliases on some of your repos to see what those do.

Git Flow

Basic flow

Executing ./git-flow-basic.sh will add aliases to support some basic git flow.

• sync-main-upstream - updates local main and origin/main with upstream/main
• sync-branch-upstream-merge-main
  • calls sync-main-upstream
  • updates feature branch from main using simple merge strategy
• sync-main - updates local main from origin/main when on a feature branch
• sync-branch-rebase-main - rebases current branch onto main; conflicts may arise
• sync-branch-continue - completes rebasing after conflict resolution

Use the following aliases if repo's main branch is named master.

• sync-master-upstream - updates local master and origin/master with upstream/master
• sync-branch-upstream-merge-master
  • calls sync-master-upstream
  • updates feature branch from master using simple merge strategy
• sync-master - updates local master from origin/master when on a feature branch
• sync-branch-rebase-master - rebases current branch onto (updated) master; conflicts may arise
• sync-branch-continue - completes rebasing after conflict resolution

Add and use those when you clearly understand what is behind. This is also a rather source of inspiration to build your own git flow than a commonly recognized pattern.

Git Town

Git town is yet another opinionated git flow toolset.

Learn and use git-town when you feel it matches the git flow you'd use.

Executing ./git-town-set.sh offers some initial settings, and works when git town is installed.

More resources on tweaking git

• First-Time Git Setup
• yevhenorlov/dotfiles@github
• Git going with aliases
• https://medium.com/@vitalyb/creating-powerful-git-aliases-3dfc0efc9a31
• robmiller/.gitconfig@github

Advanced

Subrepo

git-subrepo is a great replacement for git-submodule and git-subtree. Please, refer to:

• project docs for more details
• Repo import and export back article for a use case
• an article in Russian for a general overview (a bit outdated)

IDE minimal tweak

Tune your editor/IDE so it ensures empty line at the end of file.

Find and check the relevant setting. Examples:

• IntelliJ IDEA products: File > Settings (or ProductName > Preferences) > Editor > General -- Ensure line feed at file end on Save
• VS Code
• Sublime: Command Palette > Preferences -- change or add "ensure_newline_at_eof_on_save": true

This ensures that adding code/text at the end of file will not mark the fragment that actually had not been effectively changed (which takes place when a line doesn't end with LF character). This makes history of changes cleaner and diffs reflecting actual changes.

.editorconfig

Some editors and IDEs support .editorconfig out-of-the-box, others may require plugins. Check how your editor/IDE is supported.

Copy .editorconfig with basic settings from this project to the root directory of your own projects.

If your own projects are located somewhere under your home directory (the default case) cp ./.editorconfig ~/ will do.

Your editor/IDE may require to enable .editorconfig somewhere in its settings.

Issues?

If anything above contains errors, not quite clear or requires improvement or update, please, feel free adding an Issue.

Contributors

There are people that contributed to this project by testing instructions herein and providing their feedback. Support and willingness to help is much appreciated.

• sayckl