Merge pull request #882 from github/readme-updates
big updates to the readme and contributing guide
This commit is contained in:
risk danger olson
commit
9617da0b2c
@ -7,19 +7,6 @@ This project adheres to the [Open Code of Conduct][code-of-conduct]. By particip
|
||||
|
||||
[code-of-conduct]: http://todogroup.org/opencodeofconduct/#Git%20LFS/opensource@github.com
|
||||
|
||||
## Issue Labels
|
||||
|
||||
The Git LFS teams mark issues and pull requests with the following labels:
|
||||
|
||||
* `bug` - An issue describing a bug.
|
||||
* `enhancement` - An issue for a possible new feature.
|
||||
* `review` - An issue ready to be reviewed.
|
||||
* `release` - A checklist issue showing items marked for an upcoming release.
|
||||
* `roadmap` - A checklist issue with tasks to fulfill something from the
|
||||
[roadmap](./ROADMAP.md)
|
||||
* `storage` - Used internally by the core contributors from GitHub. It just
|
||||
means we're paying extra attention to it.
|
||||
|
||||
## Feature Requests
|
||||
|
||||
Feature requests are welcome, but will have a much better chance of being
|
||||
@ -41,6 +28,49 @@ of transferring data.
|
||||
You can see what the Git LFS team is prioritizing work on in the
|
||||
[roadmap](./ROADMAP.md).
|
||||
|
||||
## Project Management
|
||||
|
||||
The Git LFS project is managed completely through this open source project and
|
||||
its [chat room][chat]. The [roadmap][] shows the high level items that are
|
||||
prioritized for future work. Suggestions for major features should be submitted
|
||||
as a pull request that adds a markdown file to `docs/proposals` discussing the
|
||||
feature. This gives the community time to discuss it before a lot of code has
|
||||
been written. Roadmap items are linked to one or more Issue task lists ([example][roadmap-items]), with the `roadmap` label, that go into more detail.
|
||||
|
||||
[chat]: https://gitter.im/github/git-lfs
|
||||
[roadmap]: ./ROADMAP.md
|
||||
[roadmap-items]: https://github.com/github/git-lfs/issues/490
|
||||
|
||||
The Git LFS teams mark issues and pull requests with the following labels:
|
||||
|
||||
* `bug` - An issue describing a bug.
|
||||
* `enhancement` - An issue for a possible new feature.
|
||||
* `review` - A pull request ready to be reviewed.
|
||||
* `release` - A checklist issue showing items marked for an upcoming release.
|
||||
* `roadmap` - A checklist issue with tasks to fulfill something from the
|
||||
[roadmap](./ROADMAP.md)
|
||||
|
||||
## Submitting a pull request
|
||||
|
||||
0. [Fork][] and clone the repository
|
||||
0. Configure and install the dependencies: `script/bootstrap`
|
||||
0. Make sure the tests pass on your machine: `script/test`
|
||||
0. Create a new branch: `git checkout -b my-branch-name`
|
||||
0. Make your change, add tests, and make sure the tests still pass
|
||||
0. Push to your fork and [submit a pull request][pr]
|
||||
0. Accept the [GitHub CLA][cla]
|
||||
0. Pat your self on the back and wait for your pull request to be reviewed.
|
||||
|
||||
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
|
||||
|
||||
* Follow the [style guide][style] where possible.
|
||||
* Write tests.
|
||||
* Update documentation as necessary. Commands have [man pages](./docs/man).
|
||||
* Keep your change as focused as possible. If there are multiple changes you
|
||||
would like to make that are not dependent upon each other, consider submitting
|
||||
them as separate pull requests.
|
||||
* Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
|
||||
|
||||
## Building
|
||||
|
||||
Git LFS depends on having a working Go 1.5+ environment, with your standard
|
||||
@ -63,27 +93,6 @@ tests:
|
||||
$ script/integration # runs the shell tests in ./test
|
||||
$ script/cibuild # runs everything, with verbose debug output
|
||||
|
||||
## Submitting a pull request
|
||||
|
||||
0. [Fork][] and clone the repository
|
||||
0. Configure and install the dependencies: `script/bootstrap`
|
||||
0. Make sure the tests pass on your machine: `script/test`
|
||||
0. Create a new branch: `git checkout -b my-branch-name`
|
||||
0. Make your change, add tests, and make sure the tests still pass
|
||||
0. Push to your fork and [submit a pull request][pr]
|
||||
0. Accept the [GitHub CLA][cla]
|
||||
0. Pat your self on the back and wait for your pull request to be reviewed.
|
||||
|
||||
Here are a few things you can do that will increase the likelihood of your pull request being accepted:
|
||||
|
||||
- Follow the [style guide][style] where possible.
|
||||
- Write tests.
|
||||
- Update documentation as necessary. Commands have [man pages](./docs/man).
|
||||
- Keep your change as focused as possible. If there are multiple changes you
|
||||
would like to make that are not dependent upon each other, consider submitting
|
||||
them as separate pull requests.
|
||||
- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
|
||||
|
||||
## Updating 3rd party packages
|
||||
|
||||
0. Update `Nut.toml`.
|
||||
|
||||
137
README.md
137
README.md
@ -3,14 +3,9 @@
|
||||
Git LFS is a command line extension and [specification](docs/spec.md) for
|
||||
managing large files with Git. The client is written in Go, with pre-compiled
|
||||
binaries available for Mac, Windows, Linux, and FreeBSD. Check out the
|
||||
[Git LFS website][page] for a high level overview of features.
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for info on working on Git LFS and
|
||||
sending patches. Related projects are listed on the [Implementations wiki
|
||||
page][impl]. You can chat with the team at: https://gitter.im/github/git-lfs
|
||||
[Git LFS website][page] for an overview of features.
|
||||
|
||||
[page]: https://git-lfs.github.com/
|
||||
[impl]: https://github.com/github/git-lfs/wiki/Implementations
|
||||
|
||||
## Getting Started
|
||||
|
||||
@ -22,73 +17,85 @@ preferences.
|
||||
* [Binary packages are available][rel] for Windows, Mac, Linux, and FreeBSD.
|
||||
* You can build it with Go 1.5+. See the [Contributing Guide](./CONTRIBUTING.md) for instructions.
|
||||
|
||||
Once installed, you can run `git lfs install` to setup the global Git hooks
|
||||
necessary for Git LFS to work. You can get help on specific commands directly:
|
||||
[rel]: https://github.com/github/git-lfs/releases
|
||||
|
||||
Note: Git LFS requires Git v1.8.2 or higher.
|
||||
|
||||
One installed, you need to setup the global Git hooks for Git LFS. This only
|
||||
needs to be run once per machine.
|
||||
|
||||
```bash
|
||||
$ git lfs install
|
||||
```
|
||||
|
||||
Now, it's time to add some large files to a repository. The first step is to
|
||||
specify file patterns to store with Git LFS. These file patterns are stored in
|
||||
`.gitattributes`.
|
||||
|
||||
```bash
|
||||
$ mkdir large-repo
|
||||
$ cd large-repo
|
||||
$ git init
|
||||
|
||||
# Add all zip files through Git LFS
|
||||
$ git lfs track "*.zip"
|
||||
```
|
||||
|
||||
Now you're ready to push some commits:
|
||||
|
||||
```bash
|
||||
$ git add my.zip
|
||||
$ git commit -m "add zip"
|
||||
```
|
||||
|
||||
You can confirm that Git LFS is managing your zip file:
|
||||
|
||||
```bash
|
||||
$ git lfs ls-files
|
||||
my.zip
|
||||
```
|
||||
|
||||
Once you've made your commits, push your files to the Git remote:
|
||||
|
||||
```bash
|
||||
$ git push origin master
|
||||
Sending my.zip
|
||||
LFS: 12.58 MB / 12.58 MB 100.00 %
|
||||
Counting objects: 2, done.
|
||||
Delta compression using up to 8 threads.
|
||||
Compressing objects: 100% (5/5), done.
|
||||
Writing objects: 100% (5/5), 548 bytes | 0 bytes/s, done.
|
||||
Total 5 (delta 1), reused 0 (delta 0)
|
||||
To https://github.com/github/git-lfs-test
|
||||
67fcf6a..47b2002 master -> master
|
||||
```
|
||||
|
||||
## Need Help?
|
||||
|
||||
You can get help on specific commands directly:
|
||||
|
||||
```bash
|
||||
$ git lfs help <subcommand>
|
||||
```
|
||||
|
||||
The [official documentation](docs) has command references and specifications for
|
||||
the tool.
|
||||
the tool. You can ask questions in the [Git LFS chat room][chat], or [file a new
|
||||
issue][ish]. Be sure to include details about the problem so we can
|
||||
troubleshoot it.
|
||||
|
||||
Note: Git LFS requires Git v1.8.2 or higher.
|
||||
1. Include the output of `git lfs env`, which shows how your Git environment
|
||||
is setup.
|
||||
2. Include `GIT_TRACE=1` in any bad Git commands to enable debug messages.
|
||||
3. If the output includes a message like `Errors logged to /path/to/.git/lfs/objects/logs/*.log`,
|
||||
throw the contents in the issue, or as a link to a Gist or paste site.
|
||||
|
||||
[rel]: https://github.com/github/git-lfs/releases
|
||||
[chat]: https://gitter.im/github/git-lfs
|
||||
[ish]: https://github.com/github/git-lfs/issues
|
||||
|
||||
### Configuration
|
||||
## Contributing
|
||||
|
||||
Git LFS uses `.gitattributes` files to configure which files are managed by Git LFS.
|
||||
Here is a sample one that saves zips and mp3s:
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for info on working on Git LFS and
|
||||
sending patches. Related projects are listed on the [Implementations wiki
|
||||
page][impl]. You can also join [the project's chat room][chat].
|
||||
|
||||
$ cat .gitattributes
|
||||
*.mp3 filter=lfs -text
|
||||
*.zip filter=lfs -text
|
||||
|
||||
Git LFS can manage `.gitattributes` for you:
|
||||
|
||||
$ git lfs track "*.mp3"
|
||||
Tracking *.mp3
|
||||
|
||||
$ git lfs track "*.zip"
|
||||
Tracking *.zip
|
||||
|
||||
$ git lfs track
|
||||
Listing tracked paths
|
||||
*.mp3 (.gitattributes)
|
||||
*.zip (.gitattributes)
|
||||
|
||||
$ git lfs untrack "*.zip"
|
||||
Untracking *.zip
|
||||
|
||||
$ git lfs track
|
||||
Listing tracked paths
|
||||
*.mp3 (.gitattributes)
|
||||
|
||||
### Pushing commits
|
||||
|
||||
Once setup, you're ready to push some commits:
|
||||
|
||||
$ git add my.zip
|
||||
$ git commit -m "add zip"
|
||||
|
||||
You can confirm that Git LFS is managing your zip file:
|
||||
|
||||
$ git lfs ls-files
|
||||
my.zip
|
||||
|
||||
Once you've made your commits, push your files to the Git remote:
|
||||
|
||||
$ git push origin master
|
||||
Sending my.zip
|
||||
12.58 MB / 12.58 MB 100.00 %
|
||||
Counting objects: 2, done.
|
||||
Delta compression using up to 8 threads.
|
||||
Compressing objects: 100% (5/5), done.
|
||||
Writing objects: 100% (5/5), 548 bytes | 0 bytes/s, done.
|
||||
Total 5 (delta 1), reused 0 (delta 0)
|
||||
To https://github.com/github/git-lfs-test
|
||||
67fcf6a..47b2002 master -> master
|
||||
|
||||
See the [Git LFS overview](https://github.com/github/git-lfs/tree/master/docs)
|
||||
and [man pages](https://github.com/github/git-lfs/tree/master/docs/man).
|
||||
[impl]: https://github.com/github/git-lfs/wiki/Implementations
|
||||
|
||||
Loading…
Reference in New Issue
Block a user