Skip to content

Commit 10ef43f

Browse files
derrickstoleederrickstolee
committed
Merge pull request #333: update microsoft/git README
Signed-off-by: Derrick Stolee <[email protected]>
2 parents cde8988 + 2bce532 commit 10ef43f

File tree

1 file changed

+188
-137
lines changed

1 file changed

+188
-137
lines changed

‎README.md‎

Lines changed: 188 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,139 +1,190 @@
1-
Git for Windows
2-
===============
3-
4-
[![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/git-for-windows/git)
5-
[![Build status](https://github.com/git-for-windows/git/workflows/CI/PR/badge.svg)](https://github.com/git-for-windows/git/actions?query=branch%3Amain+event%3Apush)
6-
[![Join the chat at https://gitter.im/git-for-windows/git](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/git-for-windows/git?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)
7-
8-
This is [Git for Windows](http://git-for-windows.github.io/), the Windows port
9-
of [Git](http://git-scm.com/).
10-
11-
The Git for Windows project is run using a [governance
12-
model](http://git-for-windows.github.io/governance-model.html). If you
13-
encounter problems, you can report them as [GitHub
14-
issues](https://github.com/git-for-windows/git/issues), discuss them on Git
15-
for Windows' [Google Group](http://groups.google.com/group/git-for-windows),
16-
and [contribute bug
17-
fixes](https://github.com/git-for-windows/git/wiki/How-to-participate).
18-
19-
To build Git for Windows, please either install [Git for Windows'
20-
SDK](https://gitforwindows.org/#download-sdk), start its `git-bash.exe`, `cd`
21-
to your Git worktree and run `make`, or open the Git worktree as a folder in
22-
Visual Studio.
23-
24-
To verify that your build works, use one of the following methods:
25-
26-
- If you want to test the built executables within Git for Windows' SDK,
27-
prepend `<worktree>/bin-wrappers` to the `PATH`.
28-
- Alternatively, run `make install` in the Git worktree.
29-
- If you need to test this in a full installer, run `sdk build
30-
git-and-installer`.
31-
- You can also "install" Git into an existing portable Git via `make install
32-
DESTDIR=<dir>` where `<dir>` refers to the top-level directory of the
33-
portable Git. In this instance, you will want to prepend that portable Git's
34-
`/cmd` directory to the `PATH`, or test by running that portable Git's
35-
`git-bash.exe` or `git-cmd.exe`.
36-
- If you built using a recent Visual Studio, you can use the menu item
37-
`Build>Install git` (you will want to click on `Project>CMake Settings for
38-
Git` first, then click on `Edit JSON` and then point `installRoot` to the
39-
`mingw64` directory of an already-unpacked portable Git).
40-
41-
As in the previous bullet point, you will then prepend `/cmd` to the `PATH`
42-
or run using the portable Git's `git-bash.exe` or `git-cmd.exe`.
43-
- If you want to run the built executables in-place, but in a CMD instead of
44-
inside a Bash, you can run a snippet like this in the `git-bash.exe` window
45-
where Git was built (ensure that the `EOF` line has no leading spaces), and
46-
then paste into the CMD window what was put in the clipboard:
47-
48-
```sh
49-
clip.exe <<EOF
50-
set GIT_EXEC_PATH=$(cygpath -aw .)
51-
set PATH=$(cygpath -awp ".:contrib/scalar:/mingw64/bin:/usr/bin:$PATH")
52-
set GIT_TEMPLATE_DIR=$(cygpath -aw templates/blt)
53-
set GITPERLLIB=$(cygpath -aw perl/build/lib)
54-
EOF
55-
```
56-
- If you want to run the built executables in-place, but outside of Git for
57-
Windows' SDK, and without an option to set/override any environment
58-
variables (e.g. in Visual Studio's debugger), you can call the Git executable
59-
by its absolute path and use the `--exec-path` option, like so:
60-
61-
```cmd
62-
C:\git-sdk-64\usr\src\git\git.exe --exec-path=C:\git-sdk-64\usr\src\git help
63-
```
64-
65-
Note: for this to work, you have to hard-link (or copy) the `.dll` files from
66-
the `/mingw64/bin` directory to the Git worktree, or add the `/mingw64/bin`
67-
directory to the `PATH` somehow or other.
68-
69-
To make sure that you are testing the correct binary, call `./git.exe version`
70-
in the Git worktree, and then call `git version` in a directory/window where
71-
you want to test Git, and verify that they refer to the same version (you may
72-
even want to pass the command-line option `--build-options` to look at the
73-
exact commit from which the Git version was built).
74-
75-
Git - fast, scalable, distributed revision control system
1+
`microsoft/git` and the Scalar CLI
2+
==================================
3+
4+
[![CI/PR](https://github.com/microsoft/git/actions/workflows/main.yml/badge.svg)](https://github.com/microsoft/git/actions/workflows/main.yml)
5+
6+
This is `microsoft/git`, a special Git distribution to support monorepo scenarios. If you are _not_
7+
working in a monorepo, you are likely searching for
8+
[Git for Windows](http://git-for-windows.github.io/) instead of this codebase.
9+
10+
In addition to the Git command-line interface (CLI), `microsoft/git` includes the Scalar CLI to
11+
further enable working with extremely large repositories. Scalar is a tool to apply the latest
12+
recommendations and use the most advanced Git features. You can read
13+
[the Scalar CLI documentation](contrib/scalar/scalar.txt) or read our
14+
[Scalar user guide](contrib/scalar/docs/index.md) including
15+
[the philosophy of Scalar](contrib/scalar/docs/philosophy.md).
16+
17+
If you encounter problems with `microsoft/git`, please report them as
18+
[GitHub issues](https://github.com/microsoft/git/issues).
19+
20+
Why is this fork needed?
21+
=========================================================
22+
23+
Git is awesome - it's a fast, scalable, distributed version control system with an unusually rich
24+
command set that provides both high-level operations and full access to internals. What more could
25+
you ask for?
26+
27+
Well, because Git is a distributed version control system, each Git repository has a copy of all
28+
files in the entire history. As large repositories, aka _monorepos_ grow, Git can struggle to
29+
manage all that data. As Git commands like `status` and `fetch` get slower, developers stop waiting
30+
and start switching context. And context switches harm developer productivity.
31+
32+
`microsoft/git` is focused on addressing these performance woes and making the monorepo developer
33+
experience first-class. The Scalar CLI packages all of these recommendations into a simple set of
34+
commands.
35+
36+
One major feature that Scalar recommends is [partial clone](https://github.blog/2020-12-21-get-up-to-speed-with-partial-clone-and-shallow-clone/),
37+
which reduces the amount of data transferred in order to work with a Git repository. While several
38+
services such as GitHub support partial clone, Azure Repos instead has an older version of this
39+
functionality called
40+
[the GVFS protocol](https://docs.microsoft.com/en-us/azure/devops/learn/git/gvfs-architecture#gvfs-protocol).
41+
The integration with the GVFS protocol present in `microsoft/git` is not appropriate to include in
42+
the core Git client because partial clone is the official version of that functionality.
43+
44+
Downloading and Installing
45+
=========================================================
46+
47+
If you're working in a monorepo and want to take advantage of the performance boosts in
48+
`microsoft/git`, then you can download the latest version installer for your OS from the
49+
[Releases page](https://github.com/microsoft/git/releases). Alternatively, you can opt to install
50+
via the command line, using the below instructions for supported OSes:
51+
52+
## Windows
53+
54+
__Note:__ Winget is still in public preview, meaning you currently
55+
[need to take special installation steps](https://docs.microsoft.com/en-us/windows/package-manager/winget/#install-winget):
56+
Either manually install the `.appxbundle` available at the
57+
[preview version of App Installer](https://www.microsoft.com/p/app-installer/9nblggh4nns1?ocid=9nblggh4nns1_ORSEARCH_Bing&rtc=1&activetab=pivot:overviewtab),
58+
or participate in the
59+
[Windows Insider flight ring](https://insider.windows.com/https://insider.windows.com/)
60+
since `winget` is available by default on preview versions of Windows.
61+
62+
To install with Winget, run
63+
64+
```shell
65+
winget install --id microsoft.git
66+
```
67+
68+
Double-check that you have the right version by running these commands,
69+
which should have the same output:
70+
71+
```shell
72+
git version
73+
scalar version
74+
```
75+
76+
To upgrade `microsoft/git`, use the following Git command, which will download and install the latest
77+
release.
78+
79+
```shell
80+
git update-microsoft-git
81+
```
82+
83+
You may also be alerted with a notification to upgrade, which presents a single-click process for
84+
running `git update-microsoft-git`.
85+
86+
## macOS
87+
88+
To install `microsoft/git` on macOS, first [be sure that Homebrew is installed](https://brew.sh/) then
89+
install the `microsoft-git` cask with these steps:
90+
91+
```shell
92+
brew tap microsoft/git
93+
brew install --cask microsoft-git
94+
```
95+
96+
Double-check that you have the right version by running these commands,
97+
which should have the same output:
98+
99+
```shell
100+
git version
101+
scalar version
102+
```
103+
104+
To upgrade `microsoft/git`, you can run the necessary `brew` commands:
105+
106+
```shell
107+
brew update
108+
brew upgrade --cask microsoft-git
109+
```
110+
111+
Or you can run the `git update-microsoft-git` command, which will run those
112+
`brew` commands for you.
113+
114+
## Linux
115+
116+
`apt-get` support is available for Ubuntu Hirsute
117+
Hippo (21.04). Take the following steps to set up and install:
118+
119+
```shell
120+
curl -sSL https://packages.microsoft.com/config/ubuntu/21.04/prod.list | sudo tee /etc/apt/sources.list.d/microsoft-prod.list
121+
curl -sSL https://packages.microsoft.com/keys/microsoft.asc | sudo tee /etc/apt/trusted.gpg.d/microsoft.asc
122+
sudo apt-get update
123+
sudo apt-get install microsoft-git
124+
```
125+
126+
To upgrade `microsoft/git`, you can run the necessary `apt-get` commands:
127+
128+
```shell
129+
sudo apt-get update
130+
sudo apt-get upgrade microsoft-git
131+
```
132+
133+
Or you can run the `git update-microsoft-git` command, which will run those
134+
`apt-get` commands for you.
135+
136+
### Other Ubuntu/Debian distributions
137+
138+
On newer distributions*, you may use the most recent
139+
[`.deb` package](https://github.com/microsoft/git/releases). For example,
140+
you can download a specific version as follows:
141+
142+
```shell
143+
wget -O microsoft-git.deb https://github.com/microsoft/git/releases/download/v2.33.0.vfs.0.0/microsoft-git_2.33.0.vfs.0.0.deb
144+
sudo dpkg -i microsoft-git.deb
145+
```
146+
147+
Double-check that you have the right version by running these commands,
148+
which should have the same output:
149+
150+
```shell
151+
git version
152+
scalar version
153+
```
154+
155+
To upgrade, you will need to repeat these steps to reinstall.
156+
157+
*Older distributions are missing some required dependencies. Even
158+
though the package may appear to install successfully, `microsoft/
159+
git` will not function as expected. If you are running Ubuntu 18.04 or
160+
older, please follow the install from source instructions below
161+
instead of installing the debian package.
162+
163+
### Other distributions
164+
165+
You will need to compile and install `microsoft/git` from source:
166+
167+
```shell
168+
git clone https://github.com/microsoft/git microsoft-git
169+
cd microsoft-git
170+
make -j12 prefix=/usr/local INCLUDE_SCALAR=YesPlease
171+
sudo make -j12 prefix=/usr/local INCLUDE_SCALAR=YesPlease install
172+
```
173+
174+
For more assistance building Git from source, see
175+
[the INSTALL file in the core Git project](https://github.com/git/git/blob/master/INSTALL).
176+
177+
Contributing
76178
=========================================================
77179

78-
Git is a fast, scalable, distributed revision control system with an
79-
unusually rich command set that provides both high-level operations
80-
and full access to internals.
81-
82-
Git is an Open Source project covered by the GNU General Public
83-
License version 2 (some parts of it are under different licenses,
84-
compatible with the GPLv2). It was originally written by Linus
85-
Torvalds with help of a group of hackers around the net.
86-
87-
Please read the file [INSTALL][] for installation instructions.
88-
89-
Many Git online resources are accessible from <https://git-scm.com/>
90-
including full documentation and Git related tools.
91-
92-
See [Documentation/gittutorial.txt][] to get started, then see
93-
[Documentation/giteveryday.txt][] for a useful minimum set of commands, and
94-
`Documentation/git-<commandname>.txt` for documentation of each command.
95-
If git has been correctly installed, then the tutorial can also be
96-
read with `man gittutorial` or `git help tutorial`, and the
97-
documentation of each command with `man git-<commandname>` or `git help
98-
<commandname>`.
99-
100-
CVS users may also want to read [Documentation/gitcvs-migration.txt][]
101-
(`man gitcvs-migration` or `git help cvs-migration` if git is
102-
installed).
103-
104-
The user discussion and development of core Git take place on the Git
105-
mailing list -- everyone is welcome to post bug reports, feature
106-
requests, comments and patches to [email protected] (read
107-
[Documentation/SubmittingPatches][] for instructions on patch submission).
108-
To subscribe to the list, send an email with just "subscribe git" in
109-
the body to [email protected]. The mailing list archives are
110-
available at <https://lore.kernel.org/git/>,
111-
<http://marc.info/?l=git> and other archival sites.
112-
The core git mailing list is plain text (no HTML!).
113-
114-
Issues which are security relevant should be disclosed privately to
115-
the Git Security mailing list <[email protected]>.
116-
117-
The maintainer frequently sends the "What's cooking" reports that
118-
list the current status of various development topics to the mailing
119-
list. The discussion following them give a good reference for
120-
project status, development direction and remaining tasks.
121-
122-
The name "git" was given by Linus Torvalds when he wrote the very
123-
first version. He described the tool as "the stupid content tracker"
124-
and the name as (depending on your mood):
125-
126-
- random three-letter combination that is pronounceable, and not
127-
actually used by any common UNIX command. The fact that it is a
128-
mispronunciation of "get" may or may not be relevant.
129-
- stupid. contemptible and despicable. simple. Take your pick from the
130-
dictionary of slang.
131-
- "global information tracker": you're in a good mood, and it actually
132-
works for you. Angels sing, and a light suddenly fills the room.
133-
- "goddamn idiotic truckload of sh*t": when it breaks
134-
135-
[INSTALL]: INSTALL
136-
[Documentation/gittutorial.txt]: Documentation/gittutorial.txt
137-
[Documentation/giteveryday.txt]: Documentation/giteveryday.txt
138-
[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
139-
[Documentation/SubmittingPatches]: Documentation/SubmittingPatches
180+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
181+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
182+
the rights to use your contribution. For details, visit <https://cla.microsoft.com.>
183+
184+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
185+
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
186+
provided by the bot. You will only need to do this once across all repos using our CLA.
187+
188+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
189+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
190+
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

0 commit comments

Comments
 (0)