Skip to content

Commit 97c8df8

Browse files
Lessley DenningtonKyle Radervdyejeffhostetlermjcheetham
committed
Adjust README.md for microsoft/git
Microsoft's fork of Git is not quite Git for Windows, therefore we want to tell the keen reader all about it. :-) Co-authored-by: Kyle Rader <[email protected]> Co-authored-by: Victoria Dye <[email protected]> Co-authored-by: Jeff Hostetler <[email protected]> Co-authored-by: Matthew Cheetham <[email protected]> Co-authored-by: Derrick Stolee <[email protected]> Co-authored-by: Johannes Schindelin <[email protected]> Signed-off-by: Derrick Stolee <[email protected]> Signed-off-by: Johannes Schindelin <[email protected]>
1 parent 8094a1c commit 97c8df8

File tree

1 file changed

+223
-146
lines changed

1 file changed

+223
-146
lines changed

‎README.md

Lines changed: 223 additions & 146 deletions
Original file line numberDiff line numberDiff line change
@@ -1,148 +1,225 @@
1-
Git for Windows
2-
===============
3-
4-
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
5-
[![Open in Visual Studio Code](https://img.shields.io/static/v1?logo=visualstudiocode&label=&message=Open%20in%20Visual%20Studio%20Code&labelColor=2c2c32&color=007acc&logoColor=007acc)](https://open.vscode.dev/git-for-windows/git)
6-
[![Build status](https://github.com/git-for-windows/git/workflows/CI/badge.svg)](https://github.com/git-for-windows/git/actions?query=branch%3Amain+event%3Apush)
7-
[![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)
8-
9-
This is [Git for Windows](http://git-for-windows.github.io/), the Windows port
10-
of [Git](http://git-scm.com/).
11-
12-
The Git for Windows project is run using a [governance
13-
model](http://git-for-windows.github.io/governance-model.html). If you
14-
encounter problems, you can report them as [GitHub
15-
issues](https://github.com/git-for-windows/git/issues), discuss them on Git
16-
for Windows' [Google Group](http://groups.google.com/group/git-for-windows),
17-
and [contribute bug
18-
fixes](https://github.com/git-for-windows/git/wiki/How-to-participate).
19-
20-
To build Git for Windows, please either install [Git for Windows'
21-
SDK](https://gitforwindows.org/#download-sdk), start its `git-bash.exe`, `cd`
22-
to your Git worktree and run `make`, or open the Git worktree as a folder in
23-
Visual Studio.
24-
25-
To verify that your build works, use one of the following methods:
26-
27-
- If you want to test the built executables within Git for Windows' SDK,
28-
prepend `<worktree>/bin-wrappers` to the `PATH`.
29-
- Alternatively, run `make install` in the Git worktree.
30-
- If you need to test this in a full installer, run `sdk build
31-
git-and-installer`.
32-
- You can also "install" Git into an existing portable Git via `make install
33-
DESTDIR=<dir>` where `<dir>` refers to the top-level directory of the
34-
portable Git. In this instance, you will want to prepend that portable Git's
35-
`/cmd` directory to the `PATH`, or test by running that portable Git's
36-
`git-bash.exe` or `git-cmd.exe`.
37-
- If you built using a recent Visual Studio, you can use the menu item
38-
`Build>Install git` (you will want to click on `Project>CMake Settings for
39-
Git` first, then click on `Edit JSON` and then point `installRoot` to the
40-
`mingw64` directory of an already-unpacked portable Git).
41-
42-
As in the previous bullet point, you will then prepend `/cmd` to the `PATH`
43-
or run using the portable Git's `git-bash.exe` or `git-cmd.exe`.
44-
- If you want to run the built executables in-place, but in a CMD instead of
45-
inside a Bash, you can run a snippet like this in the `git-bash.exe` window
46-
where Git was built (ensure that the `EOF` line has no leading spaces), and
47-
then paste into the CMD window what was put in the clipboard:
48-
49-
```sh
50-
clip.exe <<EOF
51-
set GIT_EXEC_PATH=$(cygpath -aw .)
52-
set PATH=$(cygpath -awp ".:contrib/scalar:/mingw64/bin:/usr/bin:$PATH")
53-
set GIT_TEMPLATE_DIR=$(cygpath -aw templates/blt)
54-
set GITPERLLIB=$(cygpath -aw perl/build/lib)
55-
EOF
56-
```
57-
- If you want to run the built executables in-place, but outside of Git for
58-
Windows' SDK, and without an option to set/override any environment
59-
variables (e.g. in Visual Studio's debugger), you can call the Git executable
60-
by its absolute path and use the `--exec-path` option, like so:
61-
62-
```cmd
63-
C:\git-sdk-64\usr\src\git\git.exe --exec-path=C:\git-sdk-64\usr\src\git help
64-
```
65-
66-
Note: for this to work, you have to hard-link (or copy) the `.dll` files from
67-
the `/mingw64/bin` directory to the Git worktree, or add the `/mingw64/bin`
68-
directory to the `PATH` somehow or other.
69-
70-
To make sure that you are testing the correct binary, call `./git.exe version`
71-
in the Git worktree, and then call `git version` in a directory/window where
72-
you want to test Git, and verify that they refer to the same version (you may
73-
even want to pass the command-line option `--build-options` to look at the
74-
exact commit from which the Git version was built).
75-
76-
Git - fast, scalable, distributed revision control system
1+
`microsoft/git` and the Scalar CLI
2+
==================================
3+
4+
[![Open in Visual Studio Code](https://open.vscode.dev/badges/open-in-vscode.svg)](https://open.vscode.dev/microsoft/git)
5+
[![Build status](https://github.com/microsoft/git/workflows/CI/badge.svg)](https://github.com/microsoft/git/actions/workflows/main.yml)
6+
7+
This is `microsoft/git`, a special Git distribution to support monorepo scenarios. If you are _not_
8+
working in a monorepo, you are likely searching for
9+
[Git for Windows](https://git-for-windows.github.io/) instead of this codebase.
10+
11+
In addition to the Git command-line interface (CLI), `microsoft/git` includes the Scalar CLI to
12+
further enable working with extremely large repositories. Scalar is a tool to apply the latest
13+
recommendations and use the most advanced Git features. You can read
14+
[the Scalar CLI documentation](Documentation/scalar.txt) or read our
15+
[Scalar user guide](contrib/scalar/docs/index.md) including
16+
[the philosophy of Scalar](contrib/scalar/docs/philosophy.md).
17+
18+
If you encounter problems with `microsoft/git`, please report them as
19+
[GitHub issues](https://github.com/microsoft/git/issues).
20+
21+
Why is this fork needed?
22+
=========================================================
23+
24+
Git is awesome - it's a fast, scalable, distributed version control system with an unusually rich
25+
command set that provides both high-level operations and full access to internals. What more could
26+
you ask for?
27+
28+
Well, because Git is a distributed version control system, each Git repository has a copy of all
29+
files in the entire history. As large repositories, aka _monorepos_ grow, Git can struggle to
30+
manage all that data. As Git commands like `status` and `fetch` get slower, developers stop waiting
31+
and start switching context. And context switches harm developer productivity.
32+
33+
`microsoft/git` is focused on addressing these performance woes and making the monorepo developer
34+
experience first-class. The Scalar CLI packages all of these recommendations into a simple set of
35+
commands.
36+
37+
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/),
38+
which reduces the amount of data transferred in order to work with a Git repository. While several
39+
services such as GitHub support partial clone, Azure Repos instead has an older version of this
40+
functionality called
41+
[the GVFS protocol](https://github.com/microsoft/VFSForGit/blob/HEAD/Protocol.md).
42+
The integration with the GVFS protocol present in `microsoft/git` is not appropriate to include in
43+
the core Git client because partial clone is the official version of that functionality.
44+
45+
Downloading and Installing
7746
=========================================================
7847

79-
Git is a fast, scalable, distributed revision control system with an
80-
unusually rich command set that provides both high-level operations
81-
and full access to internals.
82-
83-
Git is an Open Source project covered by the GNU General Public
84-
License version 2 (some parts of it are under different licenses,
85-
compatible with the GPLv2). It was originally written by Linus
86-
Torvalds with help of a group of hackers around the net.
87-
88-
Please read the file [INSTALL][] for installation instructions.
89-
90-
Many Git online resources are accessible from <https://git-scm.com/>
91-
including full documentation and Git related tools.
92-
93-
See [Documentation/gittutorial.txt][] to get started, then see
94-
[Documentation/giteveryday.txt][] for a useful minimum set of commands, and
95-
`Documentation/git-<commandname>.txt` for documentation of each command.
96-
If git has been correctly installed, then the tutorial can also be
97-
read with `man gittutorial` or `git help tutorial`, and the
98-
documentation of each command with `man git-<commandname>` or `git help
99-
<commandname>`.
100-
101-
CVS users may also want to read [Documentation/gitcvs-migration.txt][]
102-
(`man gitcvs-migration` or `git help cvs-migration` if git is
103-
installed).
104-
105-
The user discussion and development of core Git take place on the Git
106-
mailing list -- everyone is welcome to post bug reports, feature
107-
requests, comments and patches to [email protected] (read
108-
[Documentation/SubmittingPatches][] for instructions on patch submission
109-
and [Documentation/CodingGuidelines][]).
110-
111-
Those wishing to help with error message, usage and informational message
112-
string translations (localization l10) should see [po/README.md][]
113-
(a `po` file is a Portable Object file that holds the translations).
114-
115-
To subscribe to the list, send an email to <[email protected]>
116-
(see https://subspace.kernel.org/subscribing.html for details). The mailing
117-
list archives are available at <https://lore.kernel.org/git/>,
118-
<https://marc.info/?l=git> and other archival sites.
119-
The core git mailing list is plain text (no HTML!).
120-
121-
Issues which are security relevant should be disclosed privately to
122-
the Git Security mailing list <[email protected]>.
123-
124-
The maintainer frequently sends the "What's cooking" reports that
125-
list the current status of various development topics to the mailing
126-
list. The discussion following them give a good reference for
127-
project status, development direction and remaining tasks.
128-
129-
The name "git" was given by Linus Torvalds when he wrote the very
130-
first version. He described the tool as "the stupid content tracker"
131-
and the name as (depending on your mood):
132-
133-
- random three-letter combination that is pronounceable, and not
134-
actually used by any common UNIX command. The fact that it is a
135-
mispronunciation of "get" may or may not be relevant.
136-
- stupid. contemptible and despicable. simple. Take your pick from the
137-
dictionary of slang.
138-
- "global information tracker": you're in a good mood, and it actually
139-
works for you. Angels sing, and a light suddenly fills the room.
140-
- "goddamn idiotic truckload of sh*t": when it breaks
141-
142-
[INSTALL]: INSTALL
143-
[Documentation/gittutorial.txt]: Documentation/gittutorial.txt
144-
[Documentation/giteveryday.txt]: Documentation/giteveryday.txt
145-
[Documentation/gitcvs-migration.txt]: Documentation/gitcvs-migration.txt
146-
[Documentation/SubmittingPatches]: Documentation/SubmittingPatches
147-
[Documentation/CodingGuidelines]: Documentation/CodingGuidelines
148-
[po/README.md]: po/README.md
48+
If you're working in a monorepo and want to take advantage of the performance boosts in
49+
`microsoft/git`, then you can download the latest version installer for your OS from the
50+
[Releases page](https://github.com/microsoft/git/releases). Alternatively, you can opt to install
51+
via the command line, using the below instructions for supported OSes:
52+
53+
## Windows
54+
55+
__Note:__ Winget is still in public preview, meaning you currently
56+
[need to take special installation steps](https://docs.microsoft.com/en-us/windows/package-manager/winget/#install-winget):
57+
Either manually install the `.appxbundle` available at the
58+
[preview version of App Installer](https://www.microsoft.com/p/app-installer/9nblggh4nns1?ocid=9nblggh4nns1_ORSEARCH_Bing&rtc=1&activetab=pivot:overviewtab),
59+
or participate in the
60+
[Windows Insider flight ring](https://insider.windows.com/https://insider.windows.com/)
61+
since `winget` is available by default on preview versions of Windows.
62+
63+
To install with Winget, run
64+
65+
```shell
66+
winget install --id microsoft.git
67+
```
68+
69+
Double-check that you have the right version by running these commands,
70+
which should have the same output:
71+
72+
```shell
73+
git version
74+
scalar version
75+
```
76+
77+
To upgrade `microsoft/git`, use the following Git command, which will download and install the latest
78+
release.
79+
80+
```shell
81+
git update-microsoft-git
82+
```
83+
84+
You may also be alerted with a notification to upgrade, which presents a single-click process for
85+
running `git update-microsoft-git`.
86+
87+
## macOS
88+
89+
To install `microsoft/git` on macOS, first [be sure that Homebrew is installed](https://brew.sh/) then
90+
install the `microsoft-git` cask with these steps:
91+
92+
```shell
93+
brew tap microsoft/git
94+
brew install --cask microsoft-git
95+
```
96+
97+
Double-check that you have the right version by running these commands,
98+
which should have the same output:
99+
100+
```shell
101+
git version
102+
scalar version
103+
```
104+
105+
To upgrade microsoft/git, you can run the necessary `brew` commands:
106+
107+
```shell
108+
brew update
109+
brew upgrade --cask microsoft-git
110+
```
111+
112+
Or you can run the `git update-microsoft-git` command, which will run those brew commands for you.
113+
114+
## Linux
115+
### Ubuntu/Debian distributions
116+
117+
On newer distributions*, you can install using the most recent Debian package.
118+
To download and validate the signature of this package, run the following:
119+
120+
```shell
121+
# Install needed packages
122+
sudo apt-get install -y curl debsig-verify
123+
124+
# Download public key signature file
125+
curl -s https://api.github.com/repos/microsoft/git/releases/latest \
126+
| grep -E 'browser_download_url.*msft-git-public.asc' \
127+
| cut -d : -f 2,3 \
128+
| tr -d \" \
129+
| xargs -I 'url' curl -L -o msft-git-public.asc 'url'
130+
131+
# De-armor public key signature file
132+
gpg --output msft-git-public.gpg --dearmor msft-git-public.asc
133+
134+
# Note that the fingerprint of this key is "B8F12E25441124E1", which you can
135+
# determine by running:
136+
gpg --show-keys msft-git-public.asc | head -n 2 | tail -n 1 | tail -c 17
137+
138+
# Copy de-armored public key to debsig keyring folder
139+
sudo mkdir /usr/share/debsig/keyrings/B8F12E25441124E1
140+
sudo mv msft-git-public.gpg /usr/share/debsig/keyrings/B8F12E25441124E1/
141+
142+
# Create an appropriate policy file
143+
sudo mkdir /etc/debsig/policies/B8F12E25441124E1
144+
cat > generic.pol << EOL
145+
<?xml version="1.0"?>
146+
<!DOCTYPE Policy SYSTEM "https://www.debian.org/debsig/1.0/policy.dtd">
147+
<Policy xmlns="https://www.debian.org/debsig/1.0/">
148+
<Origin Name="Microsoft Git" id="B8F12E25441124E1" Description="Microsoft Git public key"/>
149+
<Selection>
150+
<Required Type="origin" File="msft-git-public.gpg" id="B8F12E25441124E1"/>
151+
</Selection>
152+
<Verification MinOptional="0">
153+
<Required Type="origin" File="msft-git-public.gpg" id="B8F12E25441124E1"/>
154+
</Verification>
155+
</Policy>
156+
EOL
157+
158+
sudo mv generic.pol /etc/debsig/policies/B8F12E25441124E1/generic.pol
159+
160+
# Download Debian package
161+
curl -s https://api.github.com/repos/microsoft/git/releases/latest \
162+
| grep "browser_download_url.*deb" \
163+
| cut -d : -f 2,3 \
164+
| tr -d \" \
165+
| xargs -I 'url' curl -L -o msft-git.deb 'url'
166+
167+
# Verify
168+
debsig-verify msft-git.deb
169+
170+
# Install
171+
sudo dpkg -i msft-git.deb
172+
```
173+
174+
Double-check that you have the right version by running these commands,
175+
which should have the same output:
176+
177+
```shell
178+
git version
179+
scalar version
180+
```
181+
182+
To upgrade, you will need to repeat these steps to reinstall.
183+
184+
*Older distributions are missing some required dependencies. Even
185+
though the package may appear to install successfully, `microsoft/
186+
git` will not function as expected. If you are running `Ubuntu 20.04` or
187+
older, please follow the install from source instructions below
188+
instead of installing the debian package.
189+
190+
### Installing From Source
191+
192+
On older or other distros you will need to compile and install `microsoft/git` from source:
193+
194+
```shell
195+
git clone https://github.com/microsoft/git microsoft-git
196+
cd microsoft-git
197+
make -j12 prefix=/usr/local
198+
sudo make -j12 prefix=/usr/local install
199+
```
200+
201+
For more assistance building Git from source, see
202+
[the INSTALL file in the core Git project](https://github.com/git/git/blob/master/INSTALL).
203+
204+
#### Common Debian based dependencies
205+
While the INSTALL file covers dependencies in detail, here is a shortlist of common required dependencies on older Debian/Ubuntu distros:
206+
207+
```shell
208+
sudo apt-get update
209+
sudo apt-get install libz-dev libssl-dev libcurl4-gnutls-dev libexpat1-dev gettext cmake gcc
210+
```
211+
212+
Contributing
213+
=========================================================
214+
215+
This project welcomes contributions and suggestions. Most contributions require you to agree to a
216+
Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us
217+
the rights to use your contribution. For details, visit <https://cla.microsoft.com>.
218+
219+
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide
220+
a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions
221+
provided by the bot. You will only need to do this once across all repos using our CLA.
222+
223+
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
224+
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
225+
contact [[email protected]](mailto:[email protected]) with any additional questions or comments.

0 commit comments

Comments
 (0)