PowerShell/docs/git

Working with PowerShell repository

Get the code for the first time

git clone --recursive https://github.com/PowerShell/PowerShell

The PowerShell repository has submodules. They are required to build and test PowerShell. That's why you need --recursive, when you git clone.

If you already cloned the repo without --recursive, update submodules manually

git submodule init
git submodule update

See FAQ for details.

Branches

• Don't commit your changes directly to master. It will make the collaborative workflow messy.
• Checkout a new local branch from master for every change you want to make (bugfix, feature).
• Use the username/feature-name pattern for naming branches.
• Use lowercase-with-dashes for naming.
• Follow Linus' recommendations about history.
  • "People can (and probably should) rebase their private trees (their own work). That's a cleanup. But never other peoples code. That's a 'destroy history'... You must never EVER destroy other peoples history. You must not rebase commits other people did. Basically, if it doesn't have your sign-off on it, it's off limits: you can't rebase it, because it's not yours."

Understand branches

• master is the branch with the latest and greatest changes. It could be unstable.
• Send your pull requests to master.

Sync your local repo

Use git rebase instead of git merge and git pull, when you're updating your feature-branch.

# fetch updates all remote branch references in the repo and all submodules
# --all : tells it to do it for all remotes (handy, when you use your fork)
# -p : tells it to remove obsolete remote branch references (when they are removed from remote)
git fetch --all -p

# rebase on origin/master will rewrite your branch history
git rebase origin/master

More complex scenarios

Covering all possible git scenarios is behind the scope of the current document. Git has excellent documentation and lots of materials available online.

We are leaving few links here:

Git pretty flowchart: what to do, when your local repo became a mess.

Tags

If you are looking for the source code for a particular release, you will find it via tags.

• git tag will show you list of all tags.
• Find the tag that corresponds to the release.
• Use git checkout <tag-name> to get this version.

Note: checking out a tag will move the repo to a DETACHED HEAD state.

If you want to make changes, based on tag's version (i.e. a hotfix), checkout a new branch from this DETACHED HEAD state.

git checkout -b vors/hotfix

Recommended Git configurations

We highly recommend these configurations to help deal with whitespace, rebasing, and general use of Git.

Auto-corrects your command when it's sure (stats to status)

git config --global help.autoCorrect -1

Refuses to merge when pulling, and only pushes to branch with same name.

git config --global pull.ff only
git config --global push.default current

Shows shorter commit hashes and always shows reference names in the log.

git config --global log.abbrevCommit true
git config --global log.decorate short

Ignores whitespace changes and uses more information when merging.

git config --global apply.ignoreWhitespace change
git config --global rerere.enabled true
git config --global rerere.autoUpdate true
git config --global am.threeWay true