Skip to content

Commit cb6ddf5

Browse files
author
Sergei Vorobev
committed
Update git-related docs: basics and powershell-repository-101
1 parent 680642d commit cb6ddf5

2 files changed

Lines changed: 141 additions & 89 deletions

File tree

‎docs/git/basics.md‎

Lines changed: 10 additions & 83 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,12 @@
1-
# Git 101
1+
Getting started with git
2+
========================
23

3-
We are using Git version 2.8.1, but any recent version should be good.
4+
We are using Git version 2.9.0, but any recent version should be good.
45
It's recommended to learn the `git` command line tool for full
56
cross-platform experience and a deeper understanding of Git itself.
67

7-
There are (too) many Git tutorials on the internet. Here we post
8-
references to our favorites.
9-
10-
## Install
8+
Install
9+
---------
1110

1211
#### Windows
1312

@@ -31,7 +30,11 @@ Install via the package manager:
3130
sudo apt-get install git
3231
```
3332

34-
## Interactive tutorials
33+
Interactive tutorials
34+
----------------------
35+
36+
There are (too) many Git tutorials on the internet. Here we post
37+
references to our favorites.
3538

3639
#### Hello world
3740

@@ -50,52 +53,6 @@ learn Git in couple hours. After finishing 50+ real-world scenarios
5053
you will have a pretty good idea about what and when you can do with
5154
Git.
5255

53-
## Cheatsheets
54-
55-
#### Git pretty
56-
57-
[So you have a mess on your hands?](http://justinhileman.info/article/git-pretty/)
58-
59-
## Scenarios
60-
61-
#### Sync your local repo
62-
63-
Don't commit your changes directly to master.
64-
It would make workflow messy.
65-
66-
Always create a branch for your changes.
67-
68-
```sh
69-
# switch to master branch
70-
71-
# fetch updates all remote branch references in the repo and all submodules
72-
# --all : tells it to do it for all remotes (handy, when you use your fork)
73-
# -p : tells it to remove obsolete remote branch references (when they are removed from remote)
74-
git fetch --all -p
75-
76-
# pull updates your local files
77-
# you should call this command ONLY from master branch
78-
git pull origin master
79-
80-
# update submodules: this checks the submodules out to the commit recorded in the superproject
81-
git submodule update
82-
```
83-
84-
Then switch to your branch and do rebase
85-
86-
```
87-
git rebase master
88-
```
89-
90-
[Branches](../docs/workflow/branches.md)
91-
-------------------------------------
92-
93-
* Checkout a new local branch for every change you want to make (bugfix, feature).
94-
* Use `alias/feature-name` pattern.
95-
* Use lowercase-with-dashes for naming.
96-
* Use same branch name in superproject and all [submodules][].
97-
98-
[submodules]: https://www.git-scm.com/book/en/v2/Git-Tools-Submodules
9956

10057
Authentication
10158
--------------
@@ -128,33 +85,3 @@ Your should push to this repository instead of a fork so that the CI system can
12885
provide credentials to your pull request. If you make a pull request from a
12986
fork, the CI *will* fail.
13087

131-
Recommended Git configurations
132-
------------------------------
133-
134-
We highly recommend these configurations to help deal with whitespace,
135-
rebasing, and general use of Git.
136-
137-
> Auto-corrects your command when it's sure (`stats` to `status`)
138-
```sh
139-
git config --global help.autoCorrect -1
140-
```
141-
142-
> Refuses to merge when pulling, and only pushes to branch with same name.
143-
```sh
144-
git config --global pull.ff only
145-
git config --global push.default current
146-
```
147-
148-
> Shows shorter commit hashes and always shows reference names in the log.
149-
```sh
150-
git config --global log.abbrevCommit true
151-
git config --global log.decorate short
152-
```
153-
154-
> Ignores whitespace changes and uses more information when merging.
155-
```sh
156-
git config --global apply.ignoreWhitespace change
157-
git config --global rerere.enabled true
158-
git config --global rerere.autoUpdate true
159-
git config --global am.threeWay true
160-
```

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

Lines changed: 131 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,134 @@
1-
author: Sergei and Andy
1+
Working with PowerShell repository
2+
==================================
23

4+
#### Get the code for the first time
35

6+
```sh
7+
git clone --recursive https://github.com/PowerShell/PowerShell
8+
```
49

5-
>getting started working with PowerShell github
6-
>branch structure intro
7-
> branching (and folder) structure (where do I submit PRs? where's the release branch? dev branch? working branch?)
8-
>PR process and requirements
9-
> more
10+
PowerShell repository has **submodules**.
11+
They are required to build and test powershell.
12+
That's why you need `--recursive`, when you `clone`.
13+
14+
15+
If you already cloned the repo without `--recursive`, update submodules manually
16+
17+
```sh
18+
git submodule init
19+
git submodule update
20+
```
21+
22+
See [FAQ](../FAQ.md#why-is-my-submodule-empty) for details.
23+
24+
25+
26+
Branches
27+
---------
28+
29+
* Don't commit your changes directly to master.
30+
It would make workflow messy.
31+
* Checkout a new local branch from master for every change you want to make (bugfix, feature).
32+
* Use `alias/feature-name` pattern.
33+
* Use lowercase-with-dashes for naming.
34+
* Follow [Linus' recommendations][Linus] about history.
35+
- People can (and probably should) rebase their _private_ trees (their own
36+
work). That's a _cleanup_. But never other peoples code. That's a "destroy
37+
history"
38+
- You must never EVER destroy other peoples history. You must not rebase
39+
commits other people did. Basically, if it doesn't have your sign-off
40+
on it, it's off limits: you can't rebase it, because it's not yours.
41+
42+
#### Understand branches
43+
44+
* **master** is the branch with the latest and gratest changes.
45+
It could be unstable.
46+
* Send your Pull Requests to **master**.
47+
48+
#### Sync your local repo
49+
50+
Use **git rebase** instead of **git merge** and **git pull**, when you updating your feature-branch.
51+
52+
```sh
53+
# switch to master branch
54+
55+
# fetch updates all remote branch references in the repo and all submodules
56+
# --all : tells it to do it for all remotes (handy, when you use your fork)
57+
# -p : tells it to remove obsolete remote branch references (when they are removed from remote)
58+
git fetch --all -p
59+
60+
# pull updates your local files
61+
# you should call this command ONLY from master branch
62+
git pull origin master
63+
64+
```
65+
66+
Then switch to your branch and do rebase
67+
68+
```
69+
git rebase master
70+
```
71+
72+
#### Git pretty
73+
74+
[So you have a mess on your hands?](http://justinhileman.info/article/git-pretty/)
75+
76+
[Linus]:http://thread.gmane.org/gmane.comp.video.dri.devel/34739/focus=34744
77+
78+
79+
80+
81+
Tags
82+
------
83+
84+
If you are looking for the source code for a particular release,
85+
you will find it via **tags**.
86+
87+
* `git tag` will show you list of all tags.
88+
* Find the tag that corresponds to the release.
89+
* Use `git checkout <tag-name>` to get this version.
90+
91+
**Note:** [checking out tag][] will move the repo in [DETACHED HEAD][] state.
92+
93+
[checking out tag]:https://git-scm.com/book/en/v2/Git-Basics-Tagging#Checking-out-Tags
94+
[DETACHED HEAD]:https://www.git-tower.com/learn/git/faq/detached-head-when-checkout-commit
95+
96+
If you want to make changes, based on tag's version (i.e. a hotfix),
97+
checkout a new branch from this DETACHED HEAD state.
98+
99+
```sh
100+
git checkout -b vors/hotfix
101+
```
102+
103+
104+
105+
Recommended Git configurations
106+
==============================
107+
108+
We highly recommend these configurations to help deal with whitespace,
109+
rebasing, and general use of Git.
110+
111+
> Auto-corrects your command when it's sure (`stats` to `status`)
112+
```sh
113+
git config --global help.autoCorrect -1
114+
```
115+
116+
> Refuses to merge when pulling, and only pushes to branch with same name.
117+
```sh
118+
git config --global pull.ff only
119+
git config --global push.default current
120+
```
121+
122+
> Shows shorter commit hashes and always shows reference names in the log.
123+
```sh
124+
git config --global log.abbrevCommit true
125+
git config --global log.decorate short
126+
```
127+
128+
> Ignores whitespace changes and uses more information when merging.
129+
```sh
130+
git config --global apply.ignoreWhitespace change
131+
git config --global rerere.enabled true
132+
git config --global rerere.autoUpdate true
133+
git config --global am.threeWay true
134+
```

0 commit comments

Comments
 (0)