PowerShell/docs/git/powershell-repository-101.md

Working with PowerShell repository

Get the code for the first time

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

PowerShell repository has submodules. They are required to build and test powershell. That's why you need --recursive, when you 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 would make workflow messy.
• Checkout a new local branch from master for every change you want to make (bugfix, feature).
• Use alias/feature-name pattern.
• 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 gratest 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 updating your feature-branch.

# switch to master 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

# pull updates your local files
# you should call this command ONLY from master branch
git pull origin master

Then switch to your branch and do rebase

git rebase master

Git pretty

So you have a mess on your hands?

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 tag will move the repo in 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