diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 63ba846d..33e10373 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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`. diff --git a/README.md b/README.md index 831ec60f..8d8673ea 100644 --- a/README.md +++ b/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 ``` 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