You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+26-20Lines changed: 26 additions & 20 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -67,36 +67,41 @@ Is your Git repository bursting at the seams?
67
67
68
68
## Getting started
69
69
70
-
1.[Install the Git command-line client](https://git-scm.com/)and put it in your `PATH`. (`git-sizer` invokes `git` commands to examine the contents of your repository.)
70
+
1.Make sure that you have the [Git command-line client](https://git-scm.com/)installed. NOTE: `git-sizer` invokes `git` commands to examine the contents of your repository, so **it is required that the `git` command be in your `PATH`** when you run `git-sizer`.
71
71
72
-
2.Build:
72
+
2.Install `git-sizer`. Either:
73
73
74
-
* On Linux or OS X:
74
+
a. Install a released version of `git-sizer` (recommended):
75
75
76
-
script/bootstrap
77
-
make
76
+
* Go to [the releases page](https://github.com/github/git-sizer/releases) and download the ZIP file corresponding to your platform.
78
77
79
-
The executable file is written to `bin/git-sizer`. If you copy it to your `PATH`, you can run the program by typing `git sizer`; otherwise, you need to type the full path and filename to run it; e.g., `bin/git-sizer`.
78
+
* Unzip the file.
80
79
81
-
*On other platforms: TBD
80
+
* Move the executable file (`git-sizer` or `git-sizer.exe`) into your `PATH`.
82
81
83
-
3.Change to the directory containing the Git repository, then run
82
+
b. Build and install from source. See the instructions in [`docs/BUILDING.md`](docs/BUILDING.md).
84
83
85
-
git sizer [<opt>...]
84
+
3. Change to the directory containing the Git repository that you'd like to analyze, then run
86
85
87
-
To get a summary of the current repository, all you need is
86
+
git sizer [<option>...]
88
87
89
-
git sizer
88
+
No options are required. You can learn about available options by typing `git sizer -h` or by reading on.
90
89
91
-
Use the `--json` option to get output in JSON format, including the raw numbers.
90
+
(The above command assumes that you have added `git-sizer`to your `PATH`. If you don't add it to your `PATH`, you need to type its full path and filename to run it; e.g., `/path/to/bin/git-sizer`.)
92
91
93
92
94
93
## Usage
95
94
96
-
By default, `git-sizer` outputs its results in tabular format. For example, let's use it to check[the Linux repository](https://github.com/torvalds/linux), using the `--verbose` option to cause all statistics to be output:
95
+
By default, `git-sizer` outputs its results in tabular format. For example, let's use it to analyze[the Linux repository](https://github.com/torvalds/linux), using the `--verbose` option so that all statistics are output:
`git-sizer` has to traverse all of the history, so the analysis can take a while.
153
-
154
-
The output is a table showing the thing that was measured, its numerical value, and a rough indication of which values might be a cause for concern.
157
+
The output is a table showing the thing that was measured, its numerical value, and a rough indication of which values might be a cause for concern. In all cases, only objects that are reachable from references are included (i.e., not unreachable objects, nor objects that are reachable only from the reflogs).
155
158
156
159
The "Overall repository size" section includes repository-wide statistics about distinct objects, not including repetition. "Total size" is the sum of the sizes of the corresponding objects in their uncompressed form, measured in bytes.
157
160
158
161
The "Biggest objects" section provides information about the biggest single objects of each type, anywhere in the history.
159
162
160
163
In the "History structure" section, "maximum history depth" is the longest chain of commits in the history, and "maximum tag depth" reports the longest chain of annotated tags that point at other annotated tags.
161
164
162
-
The "Biggest checkouts" section is about the sizes of commits as checked out into a working copy. "Maximum path depth" is the largest number of path components within the repository, and "maximum path length" is the longest path in terms of bytes. "Total size of files" is the sum of all file sizes in the single biggest commit, including multiplicities if the same file appears multiple times.
165
+
The "Biggest checkouts" section is about the sizes of commits as checked out into a working copy. "Maximum path depth" is the largest number of path components for files in the working copy, and "maximum path length" is the longest path in terms of bytes. "Total size of files" is the sum of all file sizes in the single biggest commit, including multiplicities if the same file appears multiple times.
163
166
164
167
The "Value" column displays counts, using units "k" (thousand), "M" (million), "G" (billion) etc., and sizes, using units "B" (bytes), "KiB" (1024 bytes), "MiB" (1024 KiB), etc. Note that if a value overflows its counter (which should only happen for malicious repositories), the corresponding value is displayed as `∞` in tabular form, or truncated to 2³²-1 or 2⁶⁴-1 (depending on the size of the counter) in JSON mode.
165
168
166
-
The "Level of concern" column uses asterisks to indicate values that seem high compared with "typical" Git repositories. The more asterisks, the more inconvenience this value might be expected to cause. Exclamation points indicate values that are extremely high (i.e., equivalent to more than 30 asterisks).
169
+
The "Level of concern" column uses asterisks to indicate values that seem high compared with "typical" Git repositories. The more asterisks, the more inconvenience this aspect of your repository might be expected to cause. Exclamation points indicate values that are extremely high (i.e., equivalent to more than 30 asterisks).
167
170
168
171
The footnotes list the SHA-1s of the "biggest" objects referenced in the table, along with a more human-readable `<commit>:<path>` description of where that object is located in the repository's history. Given the name of a large object, you could, for example, type
169
172
@@ -173,16 +176,19 @@ at the command line to view the contents of the object. (Use `--names=none` if y
173
176
174
177
By default, only statistics above a minimal level of concern are reported. Use `--verbose` (as above) to request that all statistics be output. Use `--threshold=<value>` to suppress the reporting of statistics below a specified level of concern. (`<value>` is interpreted as a numerical value corresponding to the number of asterisks.) Use `--critical` to report only statistics with a critical level of concern (equivalent to `--threshold=30`).
175
178
179
+
If you'd like the output in machine-readable format, including exact numbers, use the `--json` option.
180
+
176
181
To get a list of other options, run
177
182
178
-
git sizer --help
183
+
git sizer -h
179
184
180
-
The Linux repository is large by most standards, and as you can see, it is pushing some of Git's limits. And indeed, some Git operations on the Linux repository (e.g., `git fsck`, `git gc`) take a while. But due to its sane structure, none of its dimensions are wildly out of proportion to the size of the code base, so it can be managed successfully using Git.
185
+
The Linux repository is large by most standards. As you can see, it is pushing some of Git's limits. And indeed, some Git operations on the Linux repository (e.g., `git fsck`, `git gc`) do take a while. But due to its sane structure, none of its dimensions are wildly out of proportion to the size of the code base, so the kernel project is managed successfully using Git.
181
186
182
187
Here is the non-verbose output for one of the famous ["git bomb"](https://kate.io/blog/git-bomb/) repositories:
Most people can just install a released version of `git-sizer`, [as described in the `README.md`](../README.md#getting-started). However, if you want to test a non-release version, or if you might want to contribute to `git-sizer`, you can also build it from source.
4
+
5
+
6
+
## Build and install using `go get`
7
+
8
+
1. Make sure that you have a recent version of the [Go language toolchain](https://golang.org/doc/install) installed and that you have set `GOPATH`.
9
+
10
+
2. Get `git-sizer` using `go get`:
11
+
12
+
go get github.com/github/git-sizer
13
+
14
+
This should fetch and compile the source code and write the executable file to `$GOPATH/bin/`.
15
+
16
+
3. Either add `$GOPATH/bin` to your `PATH`, or copy the executable file (`git-sizer` or `git-sizer.exe`) to a directory that is already in your `PATH`.
17
+
18
+
19
+
## Build using `make`
20
+
21
+
This procedure is intended for experts and people who want to help develop `git-sizer`. It should work on Linux or OS X. On other Unix-like systems, this procedure is also likely to work, provided you first [install Go manually](https://golang.org/doc/install).
22
+
23
+
1. Clone the `git-sizer` Git repository and switch to that directory:
24
+
25
+
git clone https://github.com/github/git-sizer.git
26
+
cd git-sizer
27
+
28
+
2. Install Go if necessary and create and prepare a project-local `GOPATH`:
29
+
30
+
script/bootstrap
31
+
32
+
3. (Optional) Run the automated tests:
33
+
34
+
make test
35
+
36
+
4. Build `git-sizer`:
37
+
38
+
make
39
+
40
+
If you have a C toolchain set up, you can enable support for `isatty()` (which turns off `--progress` by default if output is not to a TTY) by running
41
+
42
+
make USE_ISATTY=true
43
+
44
+
5. Copy the resulting executable file (`bin/git-sizer`) to a directory in your `PATH`.
45
+
46
+
It is also possible to cross-compile for other platforms that are supported by Go. See the comments in the `Makefile` for more information.
47
+
48
+
Note that this procedure uses a project-local `GOPATH`. This means that you can clone the repository anywhere. The disadvantage is that Go tools need to know about this `GOPATH`. The `Makefile` and the scripts under `scripts/` take care of this automatically. But if you want to run `go` commands by hand, either first set your `GOPATH`:
49
+
50
+
export GOPATH="$(pwd)/.gopath"
51
+
52
+
Or use `script/go` and `script/gofmt` rather than `go` and `gofmt`, respectively.
53
+
54
+
Unfortunately, some Go tools get confused by the symlink that is used to make the project-local `GOPATH` work. If you have this problem, it sometimes helps to run such commands from `.gopath/src/github.com/github/git-sizer/`. Alternatively, clone the project into the traditional place in your normal `GOPATH`.
0 commit comments