From ac1451ed5216d59ede93b2b633e0bcf72ffbb183 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Sat, 11 Apr 2015 08:35:32 +0200 Subject: [PATCH 01/16] Tidy up the man page summary lines * Such lines conventionally don't end with a full stop, so remove them. * Adjust the subsequent `========` lines to have the same length as the summary lines (the lengths were wrong because of an earlier renaming of the project). --- docs/man/git-lfs-clean.1.ronn | 4 ++-- docs/man/git-lfs-env.1.ronn | 4 ++-- docs/man/git-lfs-init.1.ronn | 4 ++-- docs/man/git-lfs-logs.1.ronn | 4 ++-- docs/man/git-lfs-ls-files.1.ronn | 2 +- docs/man/git-lfs-push.1.ronn | 4 ++-- docs/man/git-lfs-smudge.1.ronn | 4 ++-- docs/man/git-lfs-status.1.ronn | 2 +- docs/man/git-lfs-track.1.ronn | 4 ++-- docs/man/git-lfs-untrack.1.ronn | 4 ++-- docs/man/git-lfs.1.ronn | 4 ++-- 11 files changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/man/git-lfs-clean.1.ronn b/docs/man/git-lfs-clean.1.ronn index 86b190bc..b704ecab 100644 --- a/docs/man/git-lfs-clean.1.ronn +++ b/docs/man/git-lfs-clean.1.ronn @@ -1,5 +1,5 @@ -git-lfs-clean(1) -- Git clean filter that converts large files to pointers. -============================================================================= +git-lfs-clean(1) -- Git clean filter that converts large files to pointers +========================================================================== ## SYNOPSIS diff --git a/docs/man/git-lfs-env.1.ronn b/docs/man/git-lfs-env.1.ronn index 0975b010..58b361b9 100644 --- a/docs/man/git-lfs-env.1.ronn +++ b/docs/man/git-lfs-env.1.ronn @@ -1,5 +1,5 @@ -git-lfs-env(1) -- Display the Git LFS environment. -========================================================= +git-lfs-env(1) -- Display the Git LFS environment +================================================= ## SYNOPSIS diff --git a/docs/man/git-lfs-init.1.ronn b/docs/man/git-lfs-init.1.ronn index 0c7f9e20..41541c8f 100644 --- a/docs/man/git-lfs-init.1.ronn +++ b/docs/man/git-lfs-init.1.ronn @@ -1,5 +1,5 @@ -git-lfs-init(1) -- Ensure Git LFS is configured properly. -============================================================= +git-lfs-init(1) -- Ensure Git LFS is configured properly +======================================================== ## SYNOPSIS diff --git a/docs/man/git-lfs-logs.1.ronn b/docs/man/git-lfs-logs.1.ronn index 1d577b4c..1593dcb7 100644 --- a/docs/man/git-lfs-logs.1.ronn +++ b/docs/man/git-lfs-logs.1.ronn @@ -1,5 +1,5 @@ -git-lfs-logs(1) - Show errors from the git-lfs command. -=========================================================== +git-lfs-logs(1) - Show errors from the git-lfs command +====================================================== ## SYNOPSIS diff --git a/docs/man/git-lfs-ls-files.1.ronn b/docs/man/git-lfs-ls-files.1.ronn index 47536470..48bade34 100644 --- a/docs/man/git-lfs-ls-files.1.ronn +++ b/docs/man/git-lfs-ls-files.1.ronn @@ -1,5 +1,5 @@ git-lfs-ls-files(1) -- Show information about git lfs files in the index and working tree -============================================================================================= +========================================================================================= ## SYNOPSIS diff --git a/docs/man/git-lfs-push.1.ronn b/docs/man/git-lfs-push.1.ronn index 941843e8..67d1013c 100644 --- a/docs/man/git-lfs-push.1.ronn +++ b/docs/man/git-lfs-push.1.ronn @@ -1,5 +1,5 @@ -git-lfs-push(1) -- Push queued large files to the Git LFS endpoint. -======================================================================= +git-lfs-push(1) -- Push queued large files to the Git LFS endpoint +================================================================== ## SYNOPSIS diff --git a/docs/man/git-lfs-smudge.1.ronn b/docs/man/git-lfs-smudge.1.ronn index 7ce3afb9..43dd0b0d 100644 --- a/docs/man/git-lfs-smudge.1.ronn +++ b/docs/man/git-lfs-smudge.1.ronn @@ -1,5 +1,5 @@ -git-lfs-smudge(1) -- Git smudge filter that converts pointer in blobs to the actual content. -============================================================================================== +git-lfs-smudge(1) -- Git smudge filter that converts pointer in blobs to the actual content +=========================================================================================== ## SYNOPSIS diff --git a/docs/man/git-lfs-status.1.ronn b/docs/man/git-lfs-status.1.ronn index fb6fdf66..f15afb6c 100644 --- a/docs/man/git-lfs-status.1.ronn +++ b/docs/man/git-lfs-status.1.ronn @@ -1,5 +1,5 @@ git-lfs-status(1) -- Show the status of Git LFS files in the working tree -============================================================================ +========================================================================= ## SYNOPSIS diff --git a/docs/man/git-lfs-track.1.ronn b/docs/man/git-lfs-track.1.ronn index d2ebeafd..4406fddf 100644 --- a/docs/man/git-lfs-track.1.ronn +++ b/docs/man/git-lfs-track.1.ronn @@ -1,5 +1,5 @@ -git-lfs-track(1) - View or add Git LFS paths to Git attributes. -====================================================================== +git-lfs-track(1) - View or add Git LFS paths to Git attributes +============================================================== ## SYNOPSIS diff --git a/docs/man/git-lfs-untrack.1.ronn b/docs/man/git-lfs-untrack.1.ronn index b0a4996b..163d8323 100644 --- a/docs/man/git-lfs-untrack.1.ronn +++ b/docs/man/git-lfs-untrack.1.ronn @@ -1,5 +1,5 @@ -git-lfs-untrack(1) - Remove Git LFS paths from Git Attributes. -====================================================================== +git-lfs-untrack(1) - Remove Git LFS paths from Git Attributes +============================================================= ## SYNOPSIS diff --git a/docs/man/git-lfs.1.ronn b/docs/man/git-lfs.1.ronn index 2491d265..6a56c8a1 100644 --- a/docs/man/git-lfs.1.ronn +++ b/docs/man/git-lfs.1.ronn @@ -1,5 +1,5 @@ -git-lfs(1) -- Work with large files in Git repositories. -========================================================== +git-lfs(1) -- Work with large files in Git repositories +======================================================= ## SYNOPSIS From e151e9828aca71289dfb9db1cca1704d85fb3249 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Sat, 11 Apr 2015 09:02:18 +0200 Subject: [PATCH 02/16] Man pages: change command descriptions to the imperative voice --- docs/man/git-lfs-clean.1.ronn | 4 ++-- docs/man/git-lfs-env.1.ronn | 2 +- docs/man/git-lfs-init.1.ronn | 6 +++--- docs/man/git-lfs-logs.1.ronn | 4 ++-- docs/man/git-lfs-ls-files.1.ronn | 4 ++-- docs/man/git-lfs-push.1.ronn | 6 +++--- docs/man/git-lfs-smudge.1.ronn | 10 +++++----- docs/man/git-lfs-status.1.ronn | 2 +- docs/man/git-lfs-track.1.ronn | 6 +++--- docs/man/git-lfs-untrack.1.ronn | 2 +- 10 files changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/man/git-lfs-clean.1.ronn b/docs/man/git-lfs-clean.1.ronn index b704ecab..0c2e3f99 100644 --- a/docs/man/git-lfs-clean.1.ronn +++ b/docs/man/git-lfs-clean.1.ronn @@ -7,8 +7,8 @@ git-lfs-clean(1) -- Git clean filter that converts large files to pointers ## DESCRIPTION -Clean calculates a SHA-256 signature of the data from STDOUT, and outputs a -Git LFS pointer file. It also queues the file to be pushed by +Calculate a SHA-256 signature of the data from STDOUT, and output a +Git LFS pointer file. Also queue the file to be pushed by git-lfs-push(1). Clean is typically run by Git's clean filter, configured by the repository's diff --git a/docs/man/git-lfs-env.1.ronn b/docs/man/git-lfs-env.1.ronn index 58b361b9..d2dce2e9 100644 --- a/docs/man/git-lfs-env.1.ronn +++ b/docs/man/git-lfs-env.1.ronn @@ -7,7 +7,7 @@ git-lfs-env(1) -- Display the Git LFS environment ## DESCRIPTION -Displays the current Git LFS environment. +Display the current Git LFS environment. ## SEE ALSO diff --git a/docs/man/git-lfs-init.1.ronn b/docs/man/git-lfs-init.1.ronn index 41541c8f..421bf388 100644 --- a/docs/man/git-lfs-init.1.ronn +++ b/docs/man/git-lfs-init.1.ronn @@ -7,10 +7,10 @@ git-lfs-init(1) -- Ensure Git LFS is configured properly ## DESCRIPTION -Init performs the following actions to ensure Git LFS is setup properly: +Perform the following actions to ensure that Git LFS is setup properly: -* Sets up the clean and smudge filters under the name "lfs". -* Installs a pre-push hook to run git-lfs-push(1) +* Set up the clean and smudge filters under the name "lfs". +* Install a pre-push hook to run git-lfs-push(1) ## SEE ALSO diff --git a/docs/man/git-lfs-logs.1.ronn b/docs/man/git-lfs-logs.1.ronn index 1593dcb7..d7426f47 100644 --- a/docs/man/git-lfs-logs.1.ronn +++ b/docs/man/git-lfs-logs.1.ronn @@ -10,12 +10,12 @@ git-lfs-logs(1) - Show errors from the git-lfs command ## DESCRIPTION -The "logs" command displays errors from the git-lfs command. Any time it +Display errors from the git-lfs command. Any time it crashes, the details are saved to ".git/lfs/logs". ## OPTIONS -Without any options, `git lfs logs` will simply show the list of error logs. +Without any options, `git lfs logs` simply shows the list of error logs. * : Shows the specified error log. Use "last" to show the most recent error. diff --git a/docs/man/git-lfs-ls-files.1.ronn b/docs/man/git-lfs-ls-files.1.ronn index 48bade34..70a24b37 100644 --- a/docs/man/git-lfs-ls-files.1.ronn +++ b/docs/man/git-lfs-ls-files.1.ronn @@ -7,8 +7,8 @@ git-lfs-ls-files(1) -- Show information about git lfs files in the index and wor ## DESCRIPTION -Displays paths of Git LFS files that are found in the refspec. If no refspec is given, -the current checked out branch will be scanned. +Display paths of Git LFS files that are found in the refspec. If no refspec is given, +scan the currently checked-out branch. ## SEE ALSO diff --git a/docs/man/git-lfs-push.1.ronn b/docs/man/git-lfs-push.1.ronn index 67d1013c..c2eda4c9 100644 --- a/docs/man/git-lfs-push.1.ronn +++ b/docs/man/git-lfs-push.1.ronn @@ -7,7 +7,7 @@ git-lfs-push(1) -- Push queued large files to the Git LFS endpoint ## DESCRIPTION -Push uploads Git LFS files to the configured endpoint for the current +Upload Git LFS files to the configured endpoint for the current Git remote. Push is typically run by Git's pre-push hook. @@ -15,13 +15,13 @@ Push is typically run by Git's pre-push hook. ## OPTIONS * `--dry-run`: - Prints the files that would be pushed, without actually pushing them. + Print the files that would be pushed, without actually pushing them. * `--stdin`: Read the repo and refspec on stdin. This is used in conjunction with the pre-push hook and must be in the format used by the pre-push hook: . If --stdin is used - the command line arguments will be ignored. + the command line arguments are ignored. ## SEE ALSO diff --git a/docs/man/git-lfs-smudge.1.ronn b/docs/man/git-lfs-smudge.1.ronn index 43dd0b0d..fe0542f9 100644 --- a/docs/man/git-lfs-smudge.1.ronn +++ b/docs/man/git-lfs-smudge.1.ronn @@ -7,8 +7,8 @@ git-lfs-smudge(1) -- Git smudge filter that converts pointer in blobs to the act ## DESCRIPTION -Smudge takes a Git LFS pointer file in STDIN, parses out the pointer's ID, -and then dumps the file's contents to STDOUT. The file will be downloaded from +Read a Git LFS pointer file from STDIN, parse out the pointer's ID, +and then dump the file's contents to STDOUT. Download the file from the Git LFS endpoint if needed. The optional argument is only used for a progress bar. @@ -17,12 +17,12 @@ Git attributes. ## OPTIONS -Without any options, `git lfs smudge` will output the raw Git LFS content to +Without any options, `git lfs smudge` outputs the raw Git LFS content to STDOUT. * `--info`: - Displays the file size, and the local path to the Git LFS file. If the file - does not exist, `--` is shown. + Display the file size and the local path to the Git LFS file. If the file + does not exist, show `--`. ## SEE ALSO diff --git a/docs/man/git-lfs-status.1.ronn b/docs/man/git-lfs-status.1.ronn index f15afb6c..c9d1ebe2 100644 --- a/docs/man/git-lfs-status.1.ronn +++ b/docs/man/git-lfs-status.1.ronn @@ -7,7 +7,7 @@ git-lfs-status(1) -- Show the status of Git LFS files in the working tree ## DESCRIPTION -Displays paths of Git LFS objects that have not been pushed to the Git LFS +Display paths of Git LFS objects that have not been pushed to the Git LFS server, have differences between the index file and the current HEAD commit, and paths that have differences between the working tree and the index file. Thi first are what you would push by running git push; the second are what diff --git a/docs/man/git-lfs-track.1.ronn b/docs/man/git-lfs-track.1.ronn index 4406fddf..5aa3468f 100644 --- a/docs/man/git-lfs-track.1.ronn +++ b/docs/man/git-lfs-track.1.ronn @@ -7,9 +7,9 @@ git-lfs-track(1) - View or add Git LFS paths to Git attributes ## DESCRIPTION -The "track" command starts the given path(s) through Git LFS. The "path" \ -argument can be a file extension, or a file path. If no paths are provided, -this will simply list the tracked paths. +Start tracking the given path(s) through Git LFS. The "path" +argument can be a file extension or a file path. If no paths are provided, +simply list the tracked paths. ## EXAMPLES diff --git a/docs/man/git-lfs-untrack.1.ronn b/docs/man/git-lfs-untrack.1.ronn index 163d8323..99128a61 100644 --- a/docs/man/git-lfs-untrack.1.ronn +++ b/docs/man/git-lfs-untrack.1.ronn @@ -7,7 +7,7 @@ git-lfs-untrack(1) - Remove Git LFS paths from Git Attributes ## DESCRIPTION -The "untrack" command stops tracking the given path(s) through Git LFS. The +Stop tracking the given path(s) through Git LFS. The "path" argument can be a file extension, or a file path. ## EXAMPLES From 56b7408abbded66ee9456687c7719ac947ee6386 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Sat, 11 Apr 2015 08:35:32 +0200 Subject: [PATCH 03/16] Expand "STDIN/STDOUT" to "standard input/output" This is the more conventional spelling in manpages. --- docs/man/git-lfs-clean.1.ronn | 2 +- docs/man/git-lfs-smudge.1.ronn | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/man/git-lfs-clean.1.ronn b/docs/man/git-lfs-clean.1.ronn index 0c2e3f99..fa19f13c 100644 --- a/docs/man/git-lfs-clean.1.ronn +++ b/docs/man/git-lfs-clean.1.ronn @@ -7,7 +7,7 @@ git-lfs-clean(1) -- Git clean filter that converts large files to pointers ## DESCRIPTION -Calculate a SHA-256 signature of the data from STDOUT, and output a +Calculate a SHA-256 signature of the data from standard output, and output a Git LFS pointer file. Also queue the file to be pushed by git-lfs-push(1). diff --git a/docs/man/git-lfs-smudge.1.ronn b/docs/man/git-lfs-smudge.1.ronn index fe0542f9..18cf2787 100644 --- a/docs/man/git-lfs-smudge.1.ronn +++ b/docs/man/git-lfs-smudge.1.ronn @@ -7,8 +7,8 @@ git-lfs-smudge(1) -- Git smudge filter that converts pointer in blobs to the act ## DESCRIPTION -Read a Git LFS pointer file from STDIN, parse out the pointer's ID, -and then dump the file's contents to STDOUT. Download the file from +Read a Git LFS pointer file from standard input, parse out the pointer's ID, +and then dump the file's contents to standard output. Download the file from the Git LFS endpoint if needed. The optional argument is only used for a progress bar. @@ -18,7 +18,7 @@ Git attributes. ## OPTIONS Without any options, `git lfs smudge` outputs the raw Git LFS content to -STDOUT. +standard output. * `--info`: Display the file size and the local path to the Git LFS file. If the file From 312dc41609b002c59877941df403b0513bd67185 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Sat, 11 Apr 2015 08:35:32 +0200 Subject: [PATCH 04/16] `git lfs clean` reads from standard input, not standard output --- docs/man/git-lfs-clean.1.ronn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/git-lfs-clean.1.ronn b/docs/man/git-lfs-clean.1.ronn index fa19f13c..1ed8c5e0 100644 --- a/docs/man/git-lfs-clean.1.ronn +++ b/docs/man/git-lfs-clean.1.ronn @@ -7,7 +7,7 @@ git-lfs-clean(1) -- Git clean filter that converts large files to pointers ## DESCRIPTION -Calculate a SHA-256 signature of the data from standard output, and output a +Calculate a SHA-256 signature of the data from standard input, and output a Git LFS pointer file. Also queue the file to be pushed by git-lfs-push(1). From a66f021da88d9763c57390e7f06c54d9726fc88d Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 13 Apr 2015 10:21:48 +0200 Subject: [PATCH 05/16] `git lfs smudge`: improve man page text --- docs/man/git-lfs-smudge.1.ronn | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/man/git-lfs-smudge.1.ronn b/docs/man/git-lfs-smudge.1.ronn index 18cf2787..257bf347 100644 --- a/docs/man/git-lfs-smudge.1.ronn +++ b/docs/man/git-lfs-smudge.1.ronn @@ -3,14 +3,14 @@ git-lfs-smudge(1) -- Git smudge filter that converts pointer in blobs to the act ## SYNOPSIS -`git lfs smudge` +`git lfs smudge` [] ## DESCRIPTION -Read a Git LFS pointer file from standard input, parse out the pointer's ID, -and then dump the file's contents to standard output. Download the file from -the Git LFS endpoint if needed. The optional argument is only used for -a progress bar. +Read a Git LFS pointer file from standard input and write the contents +of the corresponding large file to standard output. If needed, +download the file's contents from the Git LFS endpoint. The +argument, if provided, is only used for a progress bar. Smudge is typically run by Git's smudge filter, configured by the repository's Git attributes. From 0a5d4abe174b6c6516467e0cd4bfe0ead8341673 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Sat, 11 Apr 2015 08:35:32 +0200 Subject: [PATCH 06/16] Explain `git lfs clean` in a more user-relevant way The fact that `git lfs clean` needs to compute a SHA-256 signature is not directly useful to the user. Instead, explain what the user most needs to know: big file in, pointer file out. --- docs/man/git-lfs-clean.1.ronn | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/man/git-lfs-clean.1.ronn b/docs/man/git-lfs-clean.1.ronn index 1ed8c5e0..5fa5fb7e 100644 --- a/docs/man/git-lfs-clean.1.ronn +++ b/docs/man/git-lfs-clean.1.ronn @@ -7,9 +7,9 @@ git-lfs-clean(1) -- Git clean filter that converts large files to pointers ## DESCRIPTION -Calculate a SHA-256 signature of the data from standard input, and output a -Git LFS pointer file. Also queue the file to be pushed by -git-lfs-push(1). +Read the contents of a large file from standard input, and write a Git +LFS pointer file for that file to standard output. Also queue the file +to be pushed by git-lfs-push(1). Clean is typically run by Git's clean filter, configured by the repository's Git attributes. From 66e59f1ce6f83efcf5743918445226a6c59cd5dd Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 13 Apr 2015 10:48:01 +0200 Subject: [PATCH 07/16] `git lfs track` and `git lfs untrack`: improve manpages --- docs/man/git-lfs-track.1.ronn | 14 +++++++------- docs/man/git-lfs-untrack.1.ronn | 8 ++++---- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/man/git-lfs-track.1.ronn b/docs/man/git-lfs-track.1.ronn index 5aa3468f..8b5c06ae 100644 --- a/docs/man/git-lfs-track.1.ronn +++ b/docs/man/git-lfs-track.1.ronn @@ -3,23 +3,23 @@ git-lfs-track(1) - View or add Git LFS paths to Git attributes ## SYNOPSIS -`git lfs track` +`git lfs track` [...] ## DESCRIPTION -Start tracking the given path(s) through Git LFS. The "path" -argument can be a file extension or a file path. If no paths are provided, -simply list the tracked paths. +Start tracking the given path(s) through Git LFS. The argument +can be a pattern or a file path. If no paths are provided, simply list +the currently-tracked paths. ## EXAMPLES -* View the paths that Git LFS is tracking currently. +* List the paths that Git LFS is currently tracking: `git lfs track` -* Track a new path in Git LFS. +* Configure Git LFS to track GIF files: - `git lfs track *.gif` + `git lfs track '*.gif'` ## SEE ALSO diff --git a/docs/man/git-lfs-untrack.1.ronn b/docs/man/git-lfs-untrack.1.ronn index 99128a61..c20a8131 100644 --- a/docs/man/git-lfs-untrack.1.ronn +++ b/docs/man/git-lfs-untrack.1.ronn @@ -3,16 +3,16 @@ git-lfs-untrack(1) - Remove Git LFS paths from Git Attributes ## SYNOPSIS -`git lfs untrack` [path]* +`git lfs untrack` ... ## DESCRIPTION -Stop tracking the given path(s) through Git LFS. The -"path" argument can be a file extension, or a file path. +Stop tracking the given path(s) through Git LFS. The argument +can be a glob pattern or a file path. ## EXAMPLES -* Prevent a path from using Git LFS clean and smudge filters. +* Configure Git LFS to stop tracking GIF files: `git lfs untrack '*.gif'` From 5408c314b742075e1e0eff74c28115f3fb93aea9 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 13 Apr 2015 10:58:59 +0200 Subject: [PATCH 08/16] `git lfs status`: improve manpage --- docs/man/git-lfs-status.1.ronn | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/man/git-lfs-status.1.ronn b/docs/man/git-lfs-status.1.ronn index c9d1ebe2..45b004a1 100644 --- a/docs/man/git-lfs-status.1.ronn +++ b/docs/man/git-lfs-status.1.ronn @@ -7,12 +7,16 @@ git-lfs-status(1) -- Show the status of Git LFS files in the working tree ## DESCRIPTION -Display paths of Git LFS objects that have not been pushed to the Git LFS -server, have differences between the index file and the current HEAD commit, -and paths that have differences between the working tree and the index file. -Thi first are what you would push by running git push; the second are what -you would commit by running git commit; the third are what you could commit -by running git add before running git commit. +Display paths of Git LFS objects that + +* have not been pushed to the Git LFS server. These are large files + that would be uploaded by `git push`. + +* have differences between the index file and the current HEAD commit. + These are large files that would be committed by `git commit`. + +* have differences between the working tree and the index file. These + are files that could be staged using `git add`. ## OPTIONS From ce2c73f7a4836bfbd0ca2638895e89688f281e17 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 13 Apr 2015 11:16:09 +0200 Subject: [PATCH 09/16] Improve `git-lfs` manpage --- docs/man/git-lfs.1.ronn | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/docs/man/git-lfs.1.ronn b/docs/man/git-lfs.1.ronn index 6a56c8a1..a8bf1241 100644 --- a/docs/man/git-lfs.1.ronn +++ b/docs/man/git-lfs.1.ronn @@ -7,11 +7,20 @@ git-lfs(1) -- Work with large files in Git repositories ## DESCRIPTION -Git LFS is a set of filters and hooks to work with large files in Git -repositories. Instead of storing the large files as Git blobs, Git LFS uses -clean and smudge filters to store a pointer in Git blobs instead. The actual -file gets pushed to a Git LFS API, and downloaded automatically when a Git -branch is checked out. +Git LFS is a system for managing and versioning large files in +association with a Git repository. Instead of storing the large files +within the Git repository as blobs, Git LFS stores special "pointer +files" in the repository, while storing the actual file contents on a +Git LFS server. The contents of the large file are downloaded +automatically when needed, for example when a Git branch containing +the large file is checked out. + +Git LFS works by using a "smudge" filter to look up the large file +contents based on the pointer file, and a "clean" filter to create a +new version of the pointer file when the large file's contents change. +It also uses a `pre-push` hook to upload the large file contents to +the Git LFS server whenever a commit containing a new large file +version is about to be pushed to the corresponding Git server. ## COMMANDS From 4eaad2383b5fd49489b5bc5c0c8a42b92378ed30 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 13 Apr 2015 11:21:44 +0200 Subject: [PATCH 10/16] Fix link to `git-lfs-env` command --- docs/man/git-lfs.1.ronn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/git-lfs.1.ronn b/docs/man/git-lfs.1.ronn index a8bf1241..f81904e8 100644 --- a/docs/man/git-lfs.1.ronn +++ b/docs/man/git-lfs.1.ronn @@ -29,7 +29,7 @@ commands and low level ("plumbing") commands. ### High-level commands (porcelain) -* git-lfs-config(1): +* git-lfs-env(1): Display the Git LFS environment. * git-lfs-init(1): Ensure Git LFS is configured properly. From 1b1e13536a7cbd190b6204884dcfe5225eebdea4 Mon Sep 17 00:00:00 2001 From: Michael Haggerty Date: Mon, 13 Apr 2015 11:27:59 +0200 Subject: [PATCH 11/16] `git lfs push`: make pre-push stdin content easier to understand Before this change, it wasn't possible in the HTML output to see which spaces separated items and which spaces were within items. --- docs/man/git-lfs-push.1.ronn | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/man/git-lfs-push.1.ronn b/docs/man/git-lfs-push.1.ronn index c2eda4c9..f8639703 100644 --- a/docs/man/git-lfs-push.1.ronn +++ b/docs/man/git-lfs-push.1.ronn @@ -20,7 +20,7 @@ Push is typically run by Git's pre-push hook. * `--stdin`: Read the repo and refspec on stdin. This is used in conjunction with the pre-push hook and must be in the format used by the pre-push hook: - . If --stdin is used + . If --stdin is used the command line arguments are ignored. ## SEE ALSO From 3f833dec59179392ce207cb18b04fb93a16ffddc Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Sun, 19 Apr 2015 12:22:15 -0600 Subject: [PATCH 12/16] clarify OID-PATH --- docs/spec.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/spec.md b/docs/spec.md index 6a855fff..efab9f12 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -84,7 +84,9 @@ $ git lfs init These filters ensure that large files aren't written into the repository proper, instead being stored locally at `.git/lfs/objects/{OID-PATH}` (where `{OID-PATH}` is a sharded filepath of the form `OID[0:2]/OID[2:4]/OID`), synchronized with -the Git LFS server as necessary. +the Git LFS server as necessary. Here is a sample path to a + + .git/lfs/objects/4d/7a/4d7a214614ab2935c943f9e0ff69d22eadbb8f32b1258daaa5e2ca24d17e2393 The `clean` filter runs as files are added to repositories. Git sends the content of the file being added as STDIN, and expects the content to write @@ -92,10 +94,8 @@ to Git as STDOUT. * Stream binary content from STDIN to a temp file, while calculating its SHA-256 signature. -* Check for the file at `.git/lfs/objects/{OID-PATH}`. -* If it does not exist: - * Queue the OID to be uploaded. - * Move the temp file to `.git/lfs/objects/{OID-PATH}`. +* Atomically move the temp file to `.git/lfs/objects/{OID-PATH}` if it does not +exist, and the sha-256 signature of the contents matches the given OID. * Delete the temp file. * Write the pointer file to STDOUT. From 434647d6f61022520e94f9afe3062b7bdc6bcfd8 Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Sun, 19 Apr 2015 12:42:54 -0600 Subject: [PATCH 13/16] clarify how git config is loaded --- docs/spec.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/spec.md b/docs/spec.md index 6a855fff..1db6c694 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -55,6 +55,14 @@ of rules that Git LFS uses to determine a repository's Git LFS server: 2. The `remote.{name}.lfsurl` string. 3. Append `/info/lfs` to the remote URL. Only works with HTTPS URLs. +Git LFS runs two `git config` commands to build up the list of values that it +uses: + +1. `git config -l -f .gitconfig` - This file is checked into the repository and +can set defaults for every user that clones the repository. +2. `git config -l` - A user's local git configuration can override any settings +from `.gitconfig`. + Here's a sample Git config file with the optional remote and Git LFS configuration options: From f18a260da8c5738ec4461226313f259d4b83c44d Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Mon, 20 Apr 2015 10:38:17 -0600 Subject: [PATCH 14/16] parse the git config from the local .gitconfig file first --- lfs/config.go | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lfs/config.go b/lfs/config.go index a499ad04..06b93dd7 100644 --- a/lfs/config.go +++ b/lfs/config.go @@ -154,7 +154,7 @@ func (c *Configuration) loadGitConfig() { panic(fmt.Errorf("Error listing git config from file: %s", err)) } - output = listOutput + "\n" + fileOutput + output = fileOutput + "\n" + listOutput lines := strings.Split(output, "\n") for _, line := range lines { From 769f54224fd82a959aba64a4281b5588b9c7a499 Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Mon, 20 Apr 2015 11:12:00 -0600 Subject: [PATCH 15/16] Remove the mention of the old push queue --- docs/man/git-lfs-clean.1.ronn | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/man/git-lfs-clean.1.ronn b/docs/man/git-lfs-clean.1.ronn index 5fa5fb7e..610b07fb 100644 --- a/docs/man/git-lfs-clean.1.ronn +++ b/docs/man/git-lfs-clean.1.ronn @@ -8,8 +8,7 @@ git-lfs-clean(1) -- Git clean filter that converts large files to pointers ## DESCRIPTION Read the contents of a large file from standard input, and write a Git -LFS pointer file for that file to standard output. Also queue the file -to be pushed by git-lfs-push(1). +LFS pointer file for that file to standard output. Clean is typically run by Git's clean filter, configured by the repository's Git attributes. From 4592dd52ad00fdf2f426e129b55093e8a76d6d45 Mon Sep 17 00:00:00 2001 From: risk danger olson Date: Mon, 20 Apr 2015 11:15:46 -0600 Subject: [PATCH 16/16] update docs to mention references, not refspec --- docs/man/git-lfs-ls-files.1.ronn | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/man/git-lfs-ls-files.1.ronn b/docs/man/git-lfs-ls-files.1.ronn index 70a24b37..2d1b49c4 100644 --- a/docs/man/git-lfs-ls-files.1.ronn +++ b/docs/man/git-lfs-ls-files.1.ronn @@ -3,12 +3,12 @@ git-lfs-ls-files(1) -- Show information about git lfs files in the index and wor ## SYNOPSIS -`git lfs ls-files` [refspec] +`git lfs ls-files` [] ## DESCRIPTION -Display paths of Git LFS files that are found in the refspec. If no refspec is given, -scan the currently checked-out branch. +Display paths of Git LFS files that are found in the given reference. If no reference is +given, scan the currently checked-out branch. ## SEE ALSO